openapi: 3.1.0
info:
  title: Featurebase API
  version: 2026-01-01.nova
  description: >-
    Welcome to the Featurebase API. This API allows you to programmatically
    interact with your Featurebase organization.


    This documentation reflects API version **2026-01-01.nova**.
  contact:
    name: Featurebase Support
    url: https://featurebase.app
  license:
    name: Proprietary
servers:
  - url: https://do.featurebase.app
    description: Production
security:
  - bearerAuth: []
tags:
  - name: API Versioning
    description: >-
      This API uses **date-based versioning**. Each version is identified by a
      release date and slug, e.g., `2026-01-01.nova`.


      **Specifying a Version**


      Include the version in the request header:


      ```

      Featurebase-Version: 2026-01-01.nova

      ```


      Or set a default version for your organization in the dashboard settings.


      **Version Compatibility**


      - **Newer versions** may add new fields to responses (always
      backwards-compatible)

      - **Breaking changes** (removed/renamed fields, changed behavior) only
      occur in new versions

      - **Your integration will continue to work** as long as you pin to a
      specific version
  - name: Authentication
    description: >-
      All API requests require authentication via API key.


      Include in headers:

      ```

      Authorization: Bearer <api-key>

      ```


      [Create and manage your API
      keys](https://auth.featurebase.app/login?redirect=/settings/api) in the
      Featurebase dashboard.
  - name: Error Handling
    description: >-
      The API uses conventional HTTP response codes to indicate success or
      failure:


      - `2xx` - Success

      - `4xx` - Client errors (bad request, unauthorized, not found, etc.)

      - `5xx` - Server errors (internal error)


      **Error Response Format**


      All errors follow a consistent format:


      ```json

      {
        "error": {
          "type": "invalid_request_error",
          "code": "resource_not_found",
          "message": "Post not found",
          "param": "id",
          "status": 404
        }
      }

      ```


      **Error Types**


      | Type | Description |

      |------|-------------|

      | `authentication_error` | Authentication failed (401) |

      | `authorization_error` | Permission denied (403) |

      | `invalid_request_error` | Invalid request parameters or resource not
      found (400, 404, 410) |

      | `api_error` | Server-side error (500) |

      | `rate_limit_error` | Too many requests (429) |
  - name: Boards
    description: >-
      Boards (post categories) organize feedback into distinct containers with
      their own settings.
  - name: Posts
    description: >-
      User-submitted feedback and feature requests. Posts belong to boards and
      can be upvoted, commented on, and tracked through statuses.
  - name: Post Statuses
    description: >-
      Post statuses define the workflow stages for posts (e.g., In Review,
      Active, Completed).
  - name: Comments
    description: >-
      Threaded discussions on posts and changelogs. Comments support voting,
      moderation, and privacy controls.
  - name: Changelogs
    description: >-
      Release notes and updates published by the organization. Changelogs keep
      users informed about new features, improvements, and fixes.
  - name: Admins
    description: >-
      Team members who manage your Featurebase organization. Admins have roles
      that define their permissions.
  - name: Custom Fields
    description: >-
      Configurable input fields for posts in your Featurebase organization.
      Custom fields allow you to collect additional structured data when users
      create posts.
  - name: Surveys
    description: >-
      Surveys allow you to collect targeted feedback from your users within your
      product. Surveys can be targeted to specific user segments or pages and
      can contain multiple questions with conditional logic.
  - name: Help Centers
    description: >-
      Help centers allow organizations to create and manage knowledge bases with
      articles and collections. Currently, Featurebase supports one help center
      per organization.
  - name: Contacts
    description: >-
      Contacts are the customers and leads in your Featurebase organization. Use
      this endpoint to list and retrieve contact information.
  - name: Teams
    description: >-
      Teams are groups within your Featurebase organization. Use this endpoint
      to list and retrieve team information for conversation assignment and
      organization management.
  - name: Companies
    description: >-
      Companies represent organizations or businesses that your users belong to.
      Use this endpoint to list and retrieve company information.
  - name: Conversations
    description: >-
      Conversations are messenger/inbox conversations in your Featurebase
      organization. Use this endpoint to list and retrieve conversation
      information.
  - name: Webhooks
    description: >-
      Webhooks allow you to receive real-time HTTP callbacks when events occur
      in your Featurebase organization. Configure webhook endpoints to subscribe
      to specific event types.
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'API key as Bearer token. Use: Authorization: Bearer sk_...'
  schemas:
    ValidationError:
      type: object
      properties:
        error:
          type: object
          properties:
            type:
              type: string
              enum:
                - invalid_request_error
              description: The type of error returned
              example: invalid_request_error
            code:
              type: string
              enum:
                - invalid_id
                - invalid_parameter
                - missing_parameter
                - invalid_cursor
                - invalid_content
                - invalid_request
                - contact_not_customer
                - contact_not_attached
                - parameter_not_supported
              description: Machine-readable error code
              example: invalid_id
            message:
              type: string
              example: Invalid post ID format
            param:
              type: string
              example: id
            status:
              type: number
              enum:
                - 400
              description: HTTP status code
              example: 400
            details:
              type: array
              items:
                type: object
                properties:
                  path:
                    type: string
                    example: body.name
                  message:
                    type: string
                    example: Required
                required:
                  - path
                  - message
              description: Additional validation error details
          required:
            - type
            - code
            - message
            - status
      required:
        - error
    NotFoundError:
      type: object
      properties:
        error:
          type: object
          properties:
            type:
              type: string
              enum:
                - invalid_request_error
              description: The type of error returned
              example: invalid_request_error
            code:
              type: string
              enum:
                - resource_not_found
                - post_not_found
                - comment_not_found
                - changelog_not_found
                - admin_not_found
                - contact_not_found
                - conversation_not_found
                - conversation_part_not_found
                - team_not_found
                - survey_not_found
                - company_not_found
                - help_center_not_found
                - collection_not_found
                - article_not_found
                - custom_field_not_found
                - board_not_found
                - voter_not_found
                - participant_not_found
                - webhook_not_found
                - version_not_supported
              description: Machine-readable error code
              example: resource_not_found
            message:
              type: string
              example: Post not found
            status:
              type: number
              enum:
                - 404
              description: HTTP status code
              example: 404
          required:
            - type
            - code
            - message
            - status
      required:
        - error
    ServerError:
      type: object
      properties:
        error:
          type: object
          properties:
            type:
              type: string
              enum:
                - api_error
              description: The type of error returned
              example: api_error
            code:
              type: string
              enum:
                - database_error
                - internal_error
                - fetch_error
                - create_error
                - update_error
                - delete_error
              description: Machine-readable error code
              example: database_error
            message:
              type: string
              example: An internal error occurred
            status:
              type: number
              enum:
                - 500
              description: HTTP status code
              example: 500
          required:
            - type
            - code
            - message
            - status
      required:
        - error
    FeaturebaseVersion:
      type: string
      example: 2026-01-01.nova
    BoardAccess:
      type: object
      properties:
        adminOnly:
          type: boolean
          description: If true, only admins can see this board
          example: false
        segments:
          type: array
          items:
            type: string
          description: Segment IDs that can access (empty = all)
          example: []
        allowedRoles:
          type: array
          items:
            type: string
          description: Role IDs allowed access (empty = all)
          example: []
        deniedRoles:
          type: array
          items:
            type: string
          description: Role IDs explicitly denied access
          example:
            - role_blocked
      required:
        - adminOnly
        - segments
        - allowedRoles
        - deniedRoles
    BoardFeatures:
      type: object
      properties:
        postingEnabled:
          type: boolean
          description: Whether users can create new posts
          example: true
        commentsEnabled:
          type: boolean
          description: Whether users can comment on posts
          example: true
        createdDatesVisible:
          type: boolean
          description: Whether creation dates are visible on posts
          example: true
      required:
        - postingEnabled
        - commentsEnabled
        - createdDatesVisible
    BoardPostDefaults:
      type: object
      properties:
        visibility:
          type: string
          enum:
            - public
            - authorOnly
            - companyOnly
          description: Default visibility for new posts
          example: public
      required:
        - visibility
    BoardLocalization:
      type: object
      properties:
        name:
          type: object
          additionalProperties:
            type: string
          description: Localized board name (language code → text)
          example:
            en: Feature Requests
            es: Solicitudes de funciones
        description:
          type:
            - object
            - 'null'
          additionalProperties:
            type: string
          description: Localized description
          example:
            en: Submit and vote on feature ideas
        formPlaceholder:
          type:
            - object
            - 'null'
          additionalProperties:
            type: string
          description: Placeholder text in the post creation form
          example:
            en: Describe your feature idea...
        heroTitle:
          type:
            - object
            - 'null'
          additionalProperties:
            type: string
          description: Hero title shown on the board page
          example:
            en: Share your ideas
        heroDescription:
          type:
            - object
            - 'null'
          additionalProperties:
            type: string
          description: Hero description/subtitle
          example: null
        submitButtonText:
          type:
            - object
            - 'null'
          additionalProperties:
            type: string
          description: Submit button text
          example:
            en: Submit Feedback
      required:
        - name
        - description
        - formPlaceholder
        - heroTitle
        - heroDescription
        - submitButtonText
    Board:
      type: object
      properties:
        object:
          type: string
          enum:
            - board
          description: Object type identifier
          example: board
        id:
          type: string
          description: Unique identifier
          example: 507f1f77bcf86cd799439011
        name:
          type: string
          description: Display name in organization's default locale
          example: Feature Requests
        icon:
          oneOf:
            - type: object
              properties:
                type:
                  type: string
                  enum:
                    - emoji
                  description: Emoji icon type
                  example: emoji
                value:
                  type: string
                  description: A single emoji character
                  example: 💡
              required:
                - type
                - value
              description: An emoji character as the board icon
              title: EmojiIcon
              example:
                type: emoji
                value: 💡
            - type: object
              properties:
                type:
                  type: string
                  enum:
                    - icon
                  description: Predefined icon type
                  example: icon
                value:
                  type: string
                  description: >-
                    Icon name from the predefined icon set (e.g., lightbulb,
                    bug, star, rocket, flag, heart, check, question, megaphone,
                    gift)
                  example: lightbulb
              required:
                - type
                - value
              description: A predefined icon from the built-in icon library
              title: PredefinedIcon
              example:
                type: icon
                value: lightbulb
            - type: object
              properties:
                type:
                  type: string
                  enum:
                    - url
                  description: External URL icon type
                  example: url
                value:
                  type: string
                  format: uri
                  description: >-
                    HTTPS URL to a custom icon image (PNG, SVG, or WebP
                    recommended)
                  example: https://cdn.example.com/icons/custom-board-icon.png
              required:
                - type
                - value
              description: A custom icon loaded from an external URL
              title: UrlIcon
              example:
                type: url
                value: https://cdn.example.com/icons/custom-board-icon.png
            - type: 'null'
          description: >-
            The board's icon. Can be one of three types:

            - **emoji**: A single emoji character (e.g., 💡, 🚀, ⭐)

            - **icon**: A predefined icon from the built-in library (e.g.,
            lightbulb, bug, star)

            - **url**: A custom image URL (HTTPS required)


            Can be `null` if no icon is set.
          title: BoardIcon
        access:
          $ref: '#/components/schemas/BoardAccess'
        features:
          $ref: '#/components/schemas/BoardFeatures'
        postDefaults:
          $ref: '#/components/schemas/BoardPostDefaults'
        customFields:
          type: array
          items:
            type: string
          description: Custom field IDs attached to this board
          example:
            - cf_priority
            - cf_category
        localization:
          $ref: '#/components/schemas/BoardLocalization'
        createdAt:
          type: string
          description: ISO 8601 timestamp when created
          example: '2023-12-12T00:00:00.000Z'
      required:
        - object
        - id
        - name
        - icon
        - access
        - features
        - postDefaults
        - customFields
        - localization
        - createdAt
    BoardList:
      type: array
      items:
        $ref: '#/components/schemas/Board'
    PostAuthor:
      type:
        - object
        - 'null'
      properties:
        id:
          type:
            - string
            - 'null'
          description: Author unique identifier
          example: 507f1f77bcf86cd799439011
        name:
          type: string
          description: Author display name
          example: John Doe
        email:
          type:
            - string
            - 'null'
          description: Author email (if available)
          example: john@example.com
        profilePicture:
          type:
            - string
            - 'null'
          description: Author profile picture URL
          example: https://cdn.example.com/avatars/john.png
        type:
          type: string
          enum:
            - admin
            - customer
            - guest
            - integration
            - bot
            - lead
          description: Type of user who authored the post
          example: customer
      required:
        - id
        - name
        - email
        - profilePicture
        - type
    PostStatus:
      type: object
      properties:
        object:
          type: string
          enum:
            - post_status
          description: Object type identifier
          example: post_status
        id:
          type: string
          description: Unique identifier
          example: 507f1f77bcf86cd799439011
        name:
          type: string
          description: Display name
          example: In Progress
        color:
          type: string
          description: Color for UI display
          example: Blue
        type:
          type: string
          enum:
            - reviewing
            - unstarted
            - active
            - completed
            - canceled
          description: The workflow stage this status represents
          example: active
        isDefault:
          type: boolean
          description: Whether this is the default status for new posts
          example: false
      required:
        - object
        - id
        - name
        - color
        - type
        - isDefault
    PostTag:
      type: object
      properties:
        id:
          type: string
          description: Tag unique identifier
          example: 507f1f77bcf86cd799439011
        name:
          type: string
          description: Tag name
          example: bug
        color:
          type:
            - string
            - 'null'
          description: Tag color hex code
          example: '#FF5722'
      required:
        - id
        - name
        - color
    PostFeatures:
      type: object
      properties:
        commentsEnabled:
          type: boolean
          description: Whether comments are allowed on this post
          example: true
      required:
        - commentsEnabled
    PostAccess:
      type: object
      properties:
        userIds:
          type: array
          items:
            type: string
          description: >-
            User IDs explicitly granted access to this post. Empty array means
            no user-level restrictions (post uses board/org visibility).
            Non-empty means only these users (plus admins) can see the post.
          example: []
        companyExternalIds:
          type: array
          items:
            type: string
          description: >-
            External company IDs explicitly granted access to this post. Empty
            array means no company-level restrictions. Non-empty means only
            users belonging to these companies can see the post.
          example: []
      required:
        - userIds
        - companyExternalIds
    Post:
      type: object
      properties:
        object:
          type: string
          enum:
            - post
          description: Object type identifier
          example: post
        id:
          type: string
          description: Unique identifier
          example: 507f1f77bcf86cd799439011
        slug:
          type: string
          description: URL-friendly slug
          example: add-dark-mode-support
        postUrl:
          type: string
          description: Full URL to view the post
          example: https://feedback.example.com/p/add-dark-mode-support
        title:
          type: string
          description: Post title
          example: Add dark mode support
        content:
          type: string
          description: Post content in HTML format
          example: >-
            <p>It would be great to have a dark mode option for the
            dashboard.</p>
        boardId:
          type: string
          description: Board (category) ID this post belongs to
          example: 507f1f77bcf86cd799439011
        author:
          $ref: '#/components/schemas/PostAuthor'
        status:
          $ref: '#/components/schemas/PostStatus'
        tags:
          type: array
          items:
            $ref: '#/components/schemas/PostTag'
          description: Tags attached to this post
          example:
            - id: 507f1f77bcf86cd799439011
              name: bug
              color: '#FF5722'
        features:
          $ref: '#/components/schemas/PostFeatures'
        upvotes:
          type: number
          description: Total number of upvotes
          example: 42
        commentCount:
          type: number
          description: Total number of comments
          example: 5
        inReview:
          type: boolean
          description: Whether the post is pending moderation review
          example: false
        isPinned:
          type: boolean
          description: Whether the post is pinned to the top
          example: false
        access:
          $ref: '#/components/schemas/PostAccess'
        assigneeId:
          type:
            - string
            - 'null'
          description: ID of the admin assigned to this post, null if unassigned
          example: 507f1f77bcf86cd799439013
        eta:
          type:
            - string
            - 'null'
          description: Estimated completion time as ISO 8601 timestamp, null if not set
          example: '2025-01-01T00:00:00.000Z'
        customFields:
          type: object
          additionalProperties: {}
          description: Custom field values keyed by field ID
          example:
            cf_priority: high
            cf_effort: 3
        createdAt:
          type: string
          description: ISO 8601 timestamp when created
          example: '2023-12-12T00:00:00.000Z'
        updatedAt:
          type: string
          description: ISO 8601 timestamp when last modified
          example: '2023-12-13T00:00:00.000Z'
      required:
        - object
        - id
        - slug
        - postUrl
        - title
        - content
        - boardId
        - author
        - status
        - tags
        - features
        - upvotes
        - commentCount
        - inReview
        - isPinned
        - access
        - assigneeId
        - eta
        - customFields
        - createdAt
        - updatedAt
    PaginationMetadata:
      type: object
      properties:
        page:
          type: number
          description: Current page number
          example: 1
        limit:
          type: number
          description: Items per page
          example: 10
        total:
          type: number
          description: Total number of items
          example: 42
        totalPages:
          type: number
          description: Total number of pages
          example: 5
      required:
        - page
        - limit
        - total
        - totalPages
      description: Pagination metadata for page-based requests
    PostList:
      type: object
      properties:
        object:
          type: string
          enum:
            - list
          description: Object type identifier
          example: list
        data:
          type: array
          items:
            $ref: '#/components/schemas/Post'
          description: Array of posts
          example: []
        nextCursor:
          type:
            - string
            - 'null'
          maxLength: 512
          description: Cursor for fetching the next page (cursor-based pagination)
          example: eyJpZCI6IjUwN2YxZjc3YmNmODZjZDc5OTQzOTAxMSJ9
        pagination:
          $ref: '#/components/schemas/PaginationMetadata'
      required:
        - object
        - data
        - nextCursor
    AuthorInput:
      type: object
      properties:
        id:
          type: string
          description: Featurebase user ID to attribute content to
          example: 507f1f77bcf86cd799439011
        userId:
          type: string
          maxLength: 255
          description: External user ID from your system (matched via SSO)
          example: usr_12345
        email:
          type: string
          format: email
          description: Author email (used to find or create user)
          example: john@example.com
        name:
          type: string
          maxLength: 255
          description: Author display name
          example: John Doe
        profilePicture:
          type: string
          description: Author profile picture URL
          example: https://example.com/avatar.png
      description: >-
        Author to attribute the post to. If not provided, uses the authenticated
        user. Supports multiple identification methods: id (Featurebase ID),
        userId (external SSO ID), or email.
    CreatePostBody:
      type: object
      properties:
        title:
          type: string
          minLength: 2
          maxLength: 512
          description: Post title
          example: Add dark mode support
        content:
          type: string
          default: ''
          description: Post content (HTML)
          example: <p>It would be great to have dark mode.</p>
        boardId:
          type: string
          description: Board ID to create post in
          example: 507f1f77bcf86cd799439011
        tags:
          anyOf:
            - type: string
              maxLength: 255
            - type: array
              items:
                type: string
                maxLength: 255
              maxItems: 50
          description: Tag names to attach
          example:
            - feature
            - ui
        commentsEnabled:
          type:
            - boolean
            - 'null'
          default: true
          description: Whether comments are enabled on this post
          example: true
        statusId:
          type: string
          description: Status ID to set
          example: 507f1f77bcf86cd799439012
        author:
          $ref: '#/components/schemas/AuthorInput'
        inReview:
          type:
            - boolean
            - 'null'
          default: false
          description: Whether post is pending moderation
          example: false
        customFields:
          type: object
          additionalProperties:
            anyOf:
              - type: array
                items:
                  type: string
                  maxLength: 1000
                maxItems: 100
              - type:
                  - string
                  - 'null'
              - type: boolean
              - type: number
              - type: string
              - type: string
                maxLength: 10000
              - type: 'null'
              - type: 'null'
          description: >-
            Custom field values. Keys must be valid ObjectIds. Values can be:
            string, boolean, number, ISO date string, array of strings, ObjectId
            string, or null.
          example:
            507f1f77bcf86cd799439011: high
        eta:
          type:
            - string
            - 'null'
          description: Estimated completion date
          example: '2025-12-31T23:59:59.000Z'
        createdAt:
          type:
            - string
            - 'null'
          description: Creation date (for backdating imports)
          example: '2025-01-15T10:30:00.000Z'
        assigneeId:
          type: string
          description: Admin ID to assign this post to
          example: 507f1f77bcf86cd799439013
        visibility:
          type: string
          enum:
            - public
            - authorOnly
            - companyOnly
          description: >-
            Post visibility. 'public' = visible to all users, 'authorOnly' =
            only visible to the author and admins, 'companyOnly' = only visible
            to users in the same company as the author
          example: public
        upvotes:
          type:
            - integer
            - 'null'
          minimum: 0
          description: >-
            Initial upvotes count. Defaults to 1 (post author is automatically
            added as voter). Use 0 to create a post without any votes.
          example: 5
      required:
        - title
        - boardId
      additionalProperties: false
    UpdatePostBody:
      type: object
      properties:
        title:
          type: string
          minLength: 2
          maxLength: 512
          description: Post title
          example: 'Updated: Add dark mode support'
        content:
          type: string
          description: Post content (HTML)
          example: <p>Updated content with more details.</p>
        boardId:
          type: string
          description: Board ID to move post to
          example: 507f1f77bcf86cd799439011
        tags:
          anyOf:
            - type: string
              maxLength: 255
            - type: array
              items:
                type: string
                maxLength: 255
              maxItems: 50
          description: Tag names to set (replaces existing)
          example:
            - feature
            - ui
        commentsEnabled:
          type:
            - boolean
            - 'null'
          description: Whether comments are enabled on this post
          example: true
        statusId:
          type: string
          description: Status ID to set
          example: 507f1f77bcf86cd799439012
        inReview:
          type:
            - boolean
            - 'null'
          description: Whether post is pending moderation
          example: false
        customFields:
          type: object
          additionalProperties:
            anyOf:
              - type: array
                items:
                  type: string
                  maxLength: 1000
                maxItems: 100
              - type:
                  - string
                  - 'null'
              - type: boolean
              - type: number
              - type: string
              - type: string
                maxLength: 10000
              - type: 'null'
              - type: 'null'
          description: >-
            Custom field values. Keys must be valid ObjectIds. Values can be:
            string, boolean, number, ISO date string, array of strings, ObjectId
            string, or null.
          example:
            507f1f77bcf86cd799439011: high
        eta:
          type:
            - string
            - 'null'
          description: Estimated completion date (null to clear)
          example: '2025-12-31T23:59:59.000Z'
        createdAt:
          type:
            - string
            - 'null'
          description: Creation date (for backdating)
          example: '2025-01-15T10:30:00.000Z'
        sendStatusUpdateEmail:
          type:
            - boolean
            - 'null'
          description: Whether to send status update email to voters
          example: false
        assigneeId:
          type:
            - string
            - 'null'
          description: Admin ID to assign this post to (null to unassign)
          example: 507f1f77bcf86cd799439013
        visibility:
          type: string
          enum:
            - public
            - authorOnly
            - companyOnly
          description: >-
            Post visibility. 'public' = visible to all users, 'authorOnly' =
            only visible to the author and admins, 'companyOnly' = only visible
            to users in the same company as the author
          example: public
        author:
          allOf:
            - $ref: '#/components/schemas/AuthorInput'
            - description: >-
                Change the post author. Supports multiple identification
                methods: id (Featurebase ID), userId (external SSO ID), or
                email. If user not found, a new user will be created.
        upvotes:
          type:
            - integer
            - 'null'
          minimum: 0
          description: >-
            Set the upvotes count directly. Use with caution as this overrides
            the actual vote count.
          example: 10
      additionalProperties: false
    DeletedPost:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier of the deleted post
          example: 507f1f77bcf86cd799439011
        object:
          type: string
          enum:
            - post
          description: Object type identifier
          example: post
        deleted:
          type: boolean
          enum:
            - true
          description: Indicates the resource was deleted
          example: true
      required:
        - id
        - object
        - deleted
    Company:
      type: object
      properties:
        object:
          type: string
          enum:
            - company
          description: Object type identifier
          example: company
        id:
          type: string
          description: Featurebase internal ID
          example: 507f1f77bcf86cd799439011
        companyId:
          type: string
          description: External company ID from your system
          example: comp_12345
        name:
          type: string
          description: Company name
          example: Acme Inc
        monthlySpend:
          type:
            - number
            - 'null'
          description: Monthly spend
          example: 5000
        industry:
          type:
            - string
            - 'null'
          description: Industry
          example: Technology
        website:
          type:
            - string
            - 'null'
          description: Company website URL
          example: https://acme.com
        plan:
          type:
            - string
            - 'null'
          description: Plan or tier name
          example: enterprise
        linkedUsers:
          type:
            - number
            - 'null'
          description: Number of users linked to this company
          example: 15
        companySize:
          type:
            - number
            - 'null'
          description: Company employee headcount
          example: 250
        lastActivity:
          type:
            - string
            - 'null'
          description: ISO date of last activity
          example: '2025-01-15T00:00:00.000Z'
        customFields:
          type: object
          additionalProperties: {}
          description: Custom field values
          example:
            location: Europe
            priority: high
        createdAt:
          type:
            - string
            - 'null'
          description: ISO date when company was created
          example: '2025-01-01T12:00:00.000Z'
        updatedAt:
          type:
            - string
            - 'null'
          description: ISO date when company was last updated
          example: '2025-01-10T15:30:00.000Z'
      required:
        - object
        - id
        - companyId
        - name
        - monthlySpend
        - industry
        - website
        - plan
        - linkedUsers
        - companySize
        - lastActivity
        - createdAt
        - updatedAt
    User:
      type: object
      properties:
        object:
          type: string
          enum:
            - contact
          description: Object type identifier
          example: contact
        id:
          type: string
          description: Unique identifier
          example: 676f0f6765bdaa7d7d760f88
        userId:
          type: string
          description: External user ID from SSO
          example: 676f0f673dbb299c8a4f3057
        organizationId:
          type: string
          description: Organization ID the user belongs to
          example: 5febde12dc56d60012d47db6
        companies:
          type: array
          items:
            $ref: '#/components/schemas/Company'
          description: Companies the user belongs to
        email:
          type:
            - string
            - 'null'
          description: User email
          example: john@example.com
        name:
          type: string
          description: User display name
          example: John Steezy
        profilePicture:
          type:
            - string
            - 'null'
          description: Profile picture URL
          example: https://fb-usercontent.fra1.cdn.digitaloceanspaces.com/anon_23.png
        commentsCreated:
          type: number
          description: Number of comments created
          example: 0
        postsCreated:
          type: number
          description: Number of posts created
          example: 0
        lastActivity:
          type: string
          description: Last activity ISO timestamp
          example: '2025-01-03T21:42:30.181Z'
        subscribedToChangelog:
          type: boolean
          description: Whether subscribed to changelog
          example: true
        manuallyOptedOutFromChangelog:
          type: boolean
          description: Whether manually opted out from changelog
          example: false
        roles:
          type: array
          items:
            type: string
          description: User roles
          example: []
        locale:
          type: string
          description: User locale
          example: en
        verified:
          type: boolean
          description: Whether email is verified
          example: true
        type:
          type: string
          enum:
            - admin
            - customer
            - guest
            - integration
            - bot
            - lead
          description: Type of user
          example: customer
        description:
          type: string
          description: User description/bio
          example: ''
        customFields:
          type: object
          additionalProperties: {}
          description: Custom field values on the user
      required:
        - object
        - id
        - name
        - type
    UserList:
      type: object
      properties:
        object:
          type: string
          enum:
            - list
          description: Object type identifier
          example: list
        data:
          type: array
          items:
            $ref: '#/components/schemas/User'
          description: Array of users
          example: []
        nextCursor:
          type:
            - string
            - 'null'
          description: Cursor for fetching the next page (cursor-based pagination)
          example: eyJpZCI6IjUwN2YxZjc3YmNmODZjZDc5OTQzOTAxMSJ9
        pagination:
          type: object
          properties:
            page:
              type: number
              description: Current page number
              example: 1
            limit:
              type: number
              description: Items per page
              example: 10
            total:
              type: number
              description: Total number of items
              example: 42
            totalPages:
              type: number
              description: Total number of pages
              example: 5
          required:
            - page
            - limit
            - total
            - totalPages
          description: Pagination metadata for page-based requests
      required:
        - object
        - data
        - nextCursor
    AddVoterResponse:
      type: object
      properties:
        object:
          type: string
          enum:
            - voter
          description: Object type identifier
          example: voter
        added:
          type: boolean
          enum:
            - true
          description: Indicates the voter was added
          example: true
        id:
          type: string
          description: Voter unique identifier
          example: 507f1f77bcf86cd799439011
        postId:
          type: string
          description: Post ID the voter was added to
          example: 507f1f77bcf86cd799439012
      required:
        - object
        - added
        - id
        - postId
    AddVoterBody:
      type: object
      properties:
        id:
          type: string
          description: Featurebase user ID to add as voter
          example: 507f1f77bcf86cd799439011
        userId:
          type: string
          maxLength: 255
          description: External user ID from your system (matched via SSO)
          example: usr_12345
        email:
          type: string
          format: email
          description: Voter email (used to find or create user)
          example: john@example.com
        name:
          type: string
          maxLength: 255
          description: Voter display name (used when creating new user)
          example: John Doe
        profilePicture:
          type: string
          description: Voter profile picture URL
          example: https://example.com/avatar.png
      additionalProperties: false
    RemoveVoterResponse:
      type: object
      properties:
        object:
          type: string
          enum:
            - voter
          description: Object type identifier
          example: voter
        removed:
          type: boolean
          enum:
            - true
          description: Indicates the voter was removed
          example: true
        id:
          type: string
          description: Voter unique identifier
          example: 507f1f77bcf86cd799439011
        postId:
          type: string
          description: Post ID the voter was removed from
          example: 507f1f77bcf86cd799439012
      required:
        - object
        - removed
        - id
        - postId
    RemoveVoterBody:
      type: object
      properties:
        id:
          type: string
          description: Featurebase user ID to remove as voter
          example: 507f1f77bcf86cd799439011
        userId:
          type: string
          maxLength: 255
          description: External user ID from your system (matched via SSO)
          example: usr_12345
        email:
          type: string
          format: email
          description: Voter email to identify user
          example: john@example.com
      additionalProperties: false
    PostStatusList:
      type: array
      items:
        $ref: '#/components/schemas/PostStatus'
    CommentAuthor:
      type:
        - object
        - 'null'
      properties:
        id:
          type:
            - string
            - 'null'
          description: Author unique identifier
          example: 507f1f77bcf86cd799439011
        name:
          type: string
          description: Author display name
          example: John Doe
        profilePicture:
          type:
            - string
            - 'null'
          description: Author profile picture URL
          example: https://cdn.example.com/avatars/john.png
        type:
          type: string
          enum:
            - admin
            - customer
            - guest
            - integration
            - bot
            - lead
          description: Type of user who authored the comment
          example: customer
      required:
        - id
        - name
        - profilePicture
        - type
    Comment:
      type: object
      properties:
        object:
          type: string
          enum:
            - comment
          description: Object type identifier
          example: comment
        id:
          type: string
          description: Unique identifier
          example: 507f1f77bcf86cd799439011
        postId:
          type:
            - string
            - 'null'
          description: Post ID this comment belongs to
          example: 507f1f77bcf86cd799439012
        changelogId:
          type:
            - string
            - 'null'
          description: Changelog ID this comment belongs to
          example: 507f1f77bcf86cd799439013
        parentCommentId:
          type:
            - string
            - 'null'
          description: Parent comment ID for replies, null for root comments
          example: 507f1f77bcf86cd799439014
        content:
          type: string
          description: Comment content in HTML format
          example: <p>This is a great idea!</p>
        author:
          $ref: '#/components/schemas/CommentAuthor'
        upvotes:
          type: number
          description: Number of upvotes
          example: 5
        downvotes:
          type: number
          description: Number of downvotes
          example: 0
        score:
          type: number
          description: Net score (upvotes - downvotes)
          example: 5
        isPrivate:
          type: boolean
          description: Whether the comment is private
          example: false
        isDeleted:
          type: boolean
          description: Whether the comment is deleted
          example: false
        isPinned:
          type: boolean
          description: Whether the comment is pinned
          example: false
        inReview:
          type: boolean
          description: Whether the comment is in review
          example: false
        isSpam:
          type: boolean
          description: Whether the comment is spam
          example: false
        createdAt:
          type: string
          description: ISO 8601 timestamp when created
          example: '2023-12-12T00:00:00.000Z'
        updatedAt:
          type: string
          description: ISO 8601 timestamp when updated
          example: '2023-12-13T00:00:00.000Z'
      required:
        - object
        - id
        - postId
        - changelogId
        - parentCommentId
        - content
        - author
        - upvotes
        - downvotes
        - score
        - isPrivate
        - isDeleted
        - isPinned
        - inReview
        - isSpam
        - createdAt
        - updatedAt
    CommentList:
      type: object
      properties:
        object:
          type: string
          enum:
            - list
          description: Object type identifier
          example: list
        data:
          type: array
          items:
            $ref: '#/components/schemas/Comment'
          description: Array of comments
          example: []
        nextCursor:
          type:
            - string
            - 'null'
          maxLength: 512
          description: Cursor for fetching the next page (cursor-based pagination)
          example: eyJpZCI6IjUwN2YxZjc3YmNmODZjZDc5OTQzOTAxMSJ9
        pagination:
          type: object
          properties:
            page:
              type: number
              description: Current page number
              example: 1
            limit:
              type: number
              description: Items per page
              example: 10
            total:
              type: number
              description: Total number of items
              example: 42
            totalPages:
              type: number
              description: Total number of pages
              example: 5
          required:
            - page
            - limit
            - total
            - totalPages
          description: Pagination metadata for page-based requests
      required:
        - object
        - data
        - nextCursor
    CreateCommentBody:
      type: object
      properties:
        content:
          type: string
          minLength: 2
          description: Comment content in HTML format
          example: <p>This is a great idea!</p>
        postId:
          type: string
          description: Post ID to comment on (accepts ObjectId or slug)
          example: 507f1f77bcf86cd799439011
        changelogId:
          type: string
          description: Changelog ID to comment on (accepts ObjectId or slug)
          example: 507f1f77bcf86cd799439012
        parentCommentId:
          type: string
          description: Parent comment ID if this is a reply
          example: 507f1f77bcf86cd799439013
        isPrivate:
          type:
            - boolean
            - 'null'
          default: false
          description: Whether the comment is private (only visible to admins)
          example: false
        sendNotification:
          type:
            - boolean
            - 'null'
          default: true
          description: Whether to notify voters of the submission about the comment
          example: true
        author:
          allOf:
            - $ref: '#/components/schemas/AuthorInput'
            - description: >-
                Author to attribute the comment to. If not provided, uses the
                authenticated user. Supports multiple identification methods: id
                (Featurebase ID), userId (external SSO ID), or email.
        createdAt:
          type:
            - string
            - 'null'
          description: >-
            Set the date when the comment was created. Useful for importing
            comments from other platforms.
          example: '2025-01-15T10:30:00.000Z'
        upvotes:
          type:
            - integer
            - 'null'
          minimum: 0
          description: >-
            Initial upvotes count. Useful for importing comments from other
            platforms. Score will be calculated as upvotes - downvotes.
          example: 5
        downvotes:
          type:
            - integer
            - 'null'
          minimum: 0
          description: >-
            Initial downvotes count. Useful for importing comments from other
            platforms. Score will be calculated as upvotes - downvotes.
          example: 0
      required:
        - content
      additionalProperties: false
    UpdateCommentBody:
      type: object
      properties:
        content:
          type: string
          minLength: 2
          description: Comment content in HTML format
          example: <p>This is my updated comment.</p>
        isPrivate:
          type:
            - boolean
            - 'null'
          description: Whether the comment is private (only visible to admins)
          example: false
        isPinned:
          type:
            - boolean
            - 'null'
          description: Whether the comment is pinned at the top
          example: true
        inReview:
          type:
            - boolean
            - 'null'
          description: Whether the comment is pending moderation review
          example: false
        createdAt:
          type:
            - string
            - 'null'
          description: Update the creation date (useful for imports)
          example: '2025-01-15T10:30:00.000Z'
        upvotes:
          type:
            - integer
            - 'null'
          minimum: 0
          description: >-
            Set the upvotes count directly. Score will be recalculated as
            upvotes - downvotes.
          example: 10
        downvotes:
          type:
            - integer
            - 'null'
          minimum: 0
          description: >-
            Set the downvotes count directly. Score will be recalculated as
            upvotes - downvotes.
          example: 2
      additionalProperties: false
    DeletedComment:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier of the deleted comment
          example: 507f1f77bcf86cd799439011
        object:
          type: string
          enum:
            - comment
          description: Object type identifier
          example: comment
        deleted:
          type: boolean
          enum:
            - true
          description: Indicates the resource was deleted
          example: true
      required:
        - id
        - object
        - deleted
    ChangelogCategory:
      type: object
      properties:
        id:
          type: string
          description: Category unique identifier
          example: 6438a1efda3640f8feb72121
        name:
          type: string
          description: Category name
          example: New Features
        roles:
          type: array
          items:
            type: string
          description: Roles allowed to view this category
          example: []
      required:
        - id
        - name
    ChangelogLocaleNotification:
      type: object
      properties:
        sendEmailNotification:
          type: boolean
          description: Whether email notification should be sent for this locale
          example: true
        hideFromBoardAndWidgets:
          type: boolean
          description: Whether the changelog is hidden from the board and widgets
          example: false
        scheduledDate:
          type:
            - string
            - 'null'
          description: Scheduled publication date as ISO 8601 timestamp
          example: '2024-01-15T12:00:00.000Z'
        emailSent:
          type: boolean
          description: Whether the email notification has been sent
          example: true
      required:
        - scheduledDate
    Changelog:
      type: object
      properties:
        object:
          type: string
          enum:
            - changelog
          description: Object type identifier
          example: changelog
        id:
          type: string
          description: Unique identifier
          example: 6457e3ff70afca5d8c27dccc
        title:
          type: string
          description: Changelog title
          example: Your awesome changelog!
        slug:
          type: string
          description: URL-friendly slug
          example: your-awesome-changelog
        url:
          type: string
          description: Public URL to view the changelog
          example: https://myorg.featurebase.app/en/changelog/your-awesome-changelog
        content:
          type: string
          description: Content in HTML format
          example: <p>Your changelog content in HTML format.</p>
        markdownContent:
          type:
            - string
            - 'null'
          description: Content in markdown format
          example: Your changelog content in markdown format.
        featuredImage:
          type:
            - string
            - 'null'
          description: Featured image URL
          example: https://cdn.example.com/images/feature.png
        date:
          type: string
          description: Publication date as ISO 8601 timestamp
          example: '2023-05-07T12:59:59.000Z'
        state:
          type: string
          enum:
            - live
            - draft
          description: State of the changelog
          example: live
        locale:
          type: string
          enum:
            - bn
            - bs
            - pt-BR
            - bg
            - ca
            - hr
            - cs
            - da
            - nl
            - en
            - et
            - fi
            - fr
            - de
            - el
            - hi
            - hu
            - id
            - it
            - ja
            - ko
            - lv
            - lt
            - ms
            - mn
            - nb
            - pl
            - pt
            - ro
            - ru
            - sr
            - zh-CN
            - sk
            - sl
            - es
            - sw
            - sv
            - th
            - zh-TW
            - tr
            - uk
            - vi
          description: Locale of the changelog
          example: en
        isPublished:
          type: boolean
          description: >-
            Whether the changelog is published (has a live version) in this
            locale
          example: true
        isDraftDiffersFromLive:
          type: boolean
          description: Whether the draft content differs from the published live content
          example: false
        publishedLocales:
          type: array
          items:
            type: string
          description: Array of locale codes where the changelog is published
          example:
            - en
            - de
        availableLocales:
          type: array
          items:
            type: string
          description: Array of locale codes where the changelog has content
          example:
            - en
            - de
            - fr
        slugs:
          type: object
          additionalProperties:
            type: string
          description: URL-friendly slugs for each locale
          example:
            en: your-awesome-changelog
            de: dein-tolles-changelog
        commentCount:
          type: number
          description: Number of comments
          example: 2
        categories:
          type: array
          items:
            $ref: '#/components/schemas/ChangelogCategory'
          description: Categories the changelog belongs to
        organization:
          type: string
          description: Organization identifier
          example: myorg
        notifications:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/ChangelogLocaleNotification'
          description: Notification settings for each locale
        allowedSegmentIds:
          type: array
          items:
            type: string
          description: Segment IDs that are allowed to view this changelog
          example: []
        emailSentToSubscribers:
          type: boolean
          description: Whether email notification was sent to subscribers
          example: true
        createdAt:
          type: string
          description: ISO 8601 timestamp when created
          example: '2023-12-12T00:00:00.000Z'
        updatedAt:
          type: string
          description: ISO 8601 timestamp when updated
          example: '2023-12-13T00:00:00.000Z'
      required:
        - object
        - id
        - title
        - slug
        - url
        - content
        - markdownContent
        - featuredImage
        - date
        - state
        - locale
        - isPublished
        - isDraftDiffersFromLive
        - publishedLocales
        - availableLocales
        - slugs
        - commentCount
        - categories
        - organization
        - notifications
        - allowedSegmentIds
        - emailSentToSubscribers
        - createdAt
        - updatedAt
    ChangelogList:
      type: object
      properties:
        object:
          type: string
          enum:
            - list
          description: Object type identifier
          example: list
        data:
          type: array
          items:
            $ref: '#/components/schemas/Changelog'
          description: Array of changelogs
          example: []
        nextCursor:
          type:
            - string
            - 'null'
          maxLength: 512
          description: Cursor for fetching the next page (cursor-based pagination)
          example: eyJpZCI6IjUwN2YxZjc3YmNmODZjZDc5OTQzOTAxMSJ9
        pagination:
          type: object
          properties:
            page:
              type: number
              description: Current page number
              example: 1
            limit:
              type: number
              description: Items per page
              example: 10
            total:
              type: number
              description: Total number of items
              example: 42
            totalPages:
              type: number
              description: Total number of pages
              example: 5
          required:
            - page
            - limit
            - total
            - totalPages
          description: Pagination metadata for page-based requests
      required:
        - object
        - data
        - nextCursor
    CreateChangelogBody:
      type: object
      properties:
        title:
          type: string
          minLength: 1
          maxLength: 512
          description: The title of the changelog
          example: New Features Update
        htmlContent:
          type: string
          description: >-
            The HTML content of the changelog. Provide either htmlContent or
            markdownContent. For images, external URLs and base64 data URIs are
            automatically processed and stored.
          example: <p>Exciting new features to explore.</p>
        markdownContent:
          type: string
          description: >-
            The markdown content of the changelog. Provide either htmlContent or
            markdownContent. For images, external URLs and base64 data URIs are
            automatically processed and stored.
          example: Exciting new features to explore.
        categories:
          type: array
          items:
            type: string
            maxLength: 255
          maxItems: 100
          description: An array of category names to which the changelog belongs
          example:
            - New
            - Fixed
            - Improved
        featuredImage:
          type: string
          description: >-
            The URL of the featured image for the changelog. External URLs will
            be uploaded to our storage.
          example: https://example.com/image.png
        allowedSegmentIds:
          type: array
          items:
            type: string
          maxItems: 100
          description: An array of segment IDs that are allowed to view the changelog
          example:
            - 507f1f77bcf86cd799439011
        locale:
          type: string
          enum:
            - bn
            - bs
            - pt-BR
            - bg
            - ca
            - hr
            - cs
            - da
            - nl
            - en
            - et
            - fi
            - fr
            - de
            - el
            - hi
            - hu
            - id
            - it
            - ja
            - ko
            - lv
            - lt
            - ms
            - mn
            - nb
            - pl
            - pt
            - ro
            - ru
            - sr
            - zh-CN
            - sk
            - sl
            - es
            - sw
            - sv
            - th
            - zh-TW
            - tr
            - uk
            - vi
          description: >-
            The locale of the changelog, defaulting to the organization default
            locale
          example: en
        date:
          type:
            - string
            - 'null'
          description: The date of the changelog
          example: '2024-01-15'
        state:
          type: string
          enum:
            - draft
            - live
          default: draft
          description: The state of the changelog (draft or live)
          example: draft
      required:
        - title
      additionalProperties: false
    UpdateChangelogBody:
      type: object
      properties:
        title:
          type: string
          minLength: 1
          maxLength: 512
          description: The title of the changelog
          example: Updated Features Release
        htmlContent:
          type: string
          description: >-
            The HTML content of the changelog. Provide either htmlContent or
            markdownContent. For images, external URLs and base64 data URIs are
            automatically processed and stored.
          example: <p>Updated features to explore.</p>
        markdownContent:
          type: string
          description: >-
            The markdown content of the changelog. Provide either htmlContent or
            markdownContent. For images, external URLs and base64 data URIs are
            automatically processed and stored.
          example: Updated features to explore.
        categories:
          type: array
          items:
            type: string
            maxLength: 255
          maxItems: 100
          description: An array of category names to which the changelog belongs
          example:
            - New
            - Fixed
            - Improved
        featuredImage:
          type: string
          description: >-
            The URL of the featured image for the changelog. External URLs will
            be uploaded to our storage.
          example: https://example.com/image.png
        allowedSegmentIds:
          type: array
          items:
            type: string
          maxItems: 100
          description: An array of segment IDs that are allowed to view the changelog
          example:
            - 507f1f77bcf86cd799439011
        date:
          type:
            - string
            - 'null'
          description: The date of the changelog
          example: '2024-01-15'
      additionalProperties: false
    DeletedChangelog:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier of the deleted changelog
          example: 507f1f77bcf86cd799439011
        object:
          type: string
          enum:
            - changelog
          description: Object type identifier
          example: changelog
        deleted:
          type: boolean
          enum:
            - true
          description: Indicates the resource was deleted
          example: true
      required:
        - id
        - object
        - deleted
    PublishUnpublishSuccess:
      type: object
      properties:
        success:
          type: boolean
          enum:
            - true
          description: Indicates the operation was successful
          example: true
        state:
          type: string
          enum:
            - published
            - scheduled
            - unpublished
          description: The state of the changelog after the operation
          example: published
      required:
        - success
    PublishChangelogBody:
      type: object
      properties:
        sendEmail:
          type:
            - boolean
            - 'null'
          default: false
          description: >-
            A flag indicating whether to send an email notification to
            subscribers.
          example: true
        locales:
          type: array
          items:
            type: string
            enum:
              - bn
              - bs
              - pt-BR
              - bg
              - ca
              - hr
              - cs
              - da
              - nl
              - en
              - et
              - fi
              - fr
              - de
              - el
              - hi
              - hu
              - id
              - it
              - ja
              - ko
              - lv
              - lt
              - ms
              - mn
              - nb
              - pl
              - pt
              - ro
              - ru
              - sr
              - zh-CN
              - sk
              - sl
              - es
              - sw
              - sv
              - th
              - zh-TW
              - tr
              - uk
              - vi
            description: Locale code for localized content
            example: en
          default: []
          description: >-
            An array of locales to publish the changelog to. An empty array
            publishes to all locales.
          example:
            - en
            - de
        scheduledDate:
          anyOf:
            - type: string
            - type: 'null'
            - type: 'null'
          description: >-
            The date when the changelog should be published. Must be a future
            date. Pass null or omit to publish immediately.
          example: '2023-12-01T00:00:00Z'
      additionalProperties: false
    UnpublishChangelogBody:
      type: object
      properties:
        locales:
          type: array
          items:
            type: string
            enum:
              - bn
              - bs
              - pt-BR
              - bg
              - ca
              - hr
              - cs
              - da
              - nl
              - en
              - et
              - fi
              - fr
              - de
              - el
              - hi
              - hu
              - id
              - it
              - ja
              - ko
              - lv
              - lt
              - ms
              - mn
              - nb
              - pl
              - pt
              - ro
              - ru
              - sr
              - zh-CN
              - sk
              - sl
              - es
              - sw
              - sv
              - th
              - zh-TW
              - tr
              - uk
              - vi
            description: Locale code for localized content
            example: en
          default: []
          description: >-
            An array of locales to unpublish the changelog from. An empty array
            unpublishes from all locales.
          example:
            - en
      additionalProperties: false
    ChangelogSubscribersImport:
      type: object
      properties:
        object:
          type: string
          enum:
            - changelog_subscribers_import
          description: Object type identifier
          example: changelog_subscribers_import
        count:
          type: number
          description: Number of email addresses processed
          example: 150
      required:
        - object
        - count
    AddChangelogSubscribersBody:
      type: object
      properties:
        emails:
          type: array
          items:
            type: string
            format: email
          minItems: 1
          maxItems: 1000
          description: Array of email addresses to add as changelog subscribers
          example:
            - john@example.com
            - jane@example.com
        locale:
          type: string
          enum:
            - bn
            - bs
            - pt-BR
            - bg
            - ca
            - hr
            - cs
            - da
            - nl
            - en
            - et
            - fi
            - fr
            - de
            - el
            - hi
            - hu
            - id
            - it
            - ja
            - ko
            - lv
            - lt
            - ms
            - mn
            - nb
            - pl
            - pt
            - ro
            - ru
            - sr
            - zh-CN
            - sk
            - sl
            - es
            - sw
            - sv
            - th
            - zh-TW
            - tr
            - uk
            - vi
          description: >-
            The locale for the subscribers. Defaults to organization default
            locale.
          example: en
      required:
        - emails
      additionalProperties: false
    ChangelogSubscribersRemoval:
      type: object
      properties:
        object:
          type: string
          enum:
            - changelog_subscribers_removal
          description: Object type identifier
          example: changelog_subscribers_removal
        count:
          type: number
          description: Number of email addresses processed
          example: 150
      required:
        - object
        - count
    RemoveChangelogSubscribersBody:
      type: object
      properties:
        emails:
          type: array
          items:
            type: string
            format: email
          minItems: 1
          maxItems: 1000
          description: Array of email addresses to remove from changelog subscribers
          example:
            - john@example.com
            - jane@example.com
      required:
        - emails
      additionalProperties: false
    Admin:
      type: object
      properties:
        object:
          type: string
          enum:
            - admin
          description: Object type identifier
          example: admin
        id:
          type: string
          description: Unique identifier
          example: 5fef50c5e9458a0012f82456
        name:
          type: string
          description: Admin display name
          example: John Doe
        email:
          type: string
          description: Admin email address
          example: john@example.com
        profilePicture:
          type:
            - string
            - 'null'
          description: Profile picture URL
          example: https://example.com/avatar.png
        roleId:
          type: string
          description: Role ID assigned to this admin
          example: 6648f22b7b23fb2f4307aafe
      required:
        - object
        - id
    AdminList:
      type: object
      properties:
        object:
          type: string
          enum:
            - list
          description: Object type identifier
          example: list
        data:
          type: array
          items:
            $ref: '#/components/schemas/Admin'
          description: Array of admins
          example: []
        nextCursor:
          type:
            - string
            - 'null'
          description: Cursor for fetching the next page (cursor-based pagination)
          example: null
        pagination:
          type: object
          properties:
            page:
              type: number
              description: Current page number
              example: 1
            limit:
              type: number
              description: Items per page
              example: 10
            total:
              type: number
              description: Total number of items
              example: 42
            totalPages:
              type: number
              description: Total number of pages
              example: 5
          required:
            - page
            - limit
            - total
            - totalPages
          description: Pagination metadata for page-based requests
      required:
        - object
        - data
        - nextCursor
    AdminRolePermissions:
      type: object
      properties:
        view_comments_private:
          type: boolean
          description: View private comments
          example: false
        manage_comments:
          type: boolean
          description: Manage comments
          example: true
        manage_comments_private:
          type: boolean
          description: Manage private comments
          example: false
        set_comment_pinned:
          type: boolean
          description: Pin/unpin comments
          example: true
        moderate_comments:
          type: boolean
          description: Moderate comments
          example: true
        set_post_category:
          type: boolean
          description: Set post category/board
          example: true
        set_post_pinned:
          type: boolean
          description: Pin/unpin posts
          example: true
        set_post_eta:
          type: boolean
          description: Set post ETA
          example: true
        set_post_tags:
          type: boolean
          description: Set post tags
          example: true
        set_post_author:
          type: boolean
          description: Set post author
          example: true
        set_post_status:
          type: boolean
          description: Set post status
          example: true
        set_post_assignee:
          type: boolean
          description: Assign posts
          example: true
        set_post_custom_fields:
          type: boolean
          description: Set post custom fields
          example: true
        post_vote_on_behalf:
          type: boolean
          description: Vote on posts on behalf of users
          example: false
        post_merge:
          type: boolean
          description: Merge posts
          example: true
        post_import:
          type: boolean
          description: Import posts
          example: false
        post_export:
          type: boolean
          description: Export posts
          example: true
        moderate_posts:
          type: boolean
          description: Moderate posts
          example: true
        view_users:
          type: boolean
          description: View users
          example: true
        manage_users:
          type: boolean
          description: Manage users
          example: true
        view_posts_private:
          type: boolean
          description: View private posts
          example: false
        view_private_post_tags:
          type: boolean
          description: View private post tags
          example: false
        manage_changelogs:
          type: boolean
          description: Manage changelogs
          example: true
        manage_surveys:
          type: boolean
          description: Manage surveys
          example: true
        manage_branding:
          type: boolean
          description: Manage branding
          example: false
        manage_billing:
          type: boolean
          description: Manage billing
          example: false
        manage_team_members:
          type: boolean
          description: Manage team members
          example: true
        manage_sso:
          type: boolean
          description: Manage SSO
          example: false
        manage_api:
          type: boolean
          description: Manage API settings
          example: false
        manage_statuses:
          type: boolean
          description: Manage post statuses
          example: true
        manage_boards:
          type: boolean
          description: Manage boards
          example: true
        manage_post_tags:
          type: boolean
          description: Manage post tags
          example: true
        manage_custom_fields:
          type: boolean
          description: Manage custom fields
          example: true
        manage_moderation_settings:
          type: boolean
          description: Manage moderation settings
          example: true
        manage_roadmap:
          type: boolean
          description: Manage roadmap
          example: true
        manage_user_roles:
          type: boolean
          description: Manage user roles
          example: true
        manage_prioritization:
          type: boolean
          description: Manage prioritization
          example: true
        manage_notifications:
          type: boolean
          description: Manage notifications
          example: true
        manage_custom_domain:
          type: boolean
          description: Manage custom domain
          example: false
        manage_integrations:
          type: boolean
          description: Manage integrations
          example: false
        use_integrations:
          type: boolean
          description: Use integrations
          example: true
        manage_help_center:
          type: boolean
          description: Manage help center
          example: true
        auto_approve_posts:
          type: boolean
          description: Auto-approve posts
          example: false
      description: Role permissions
    AdminRole:
      type: object
      properties:
        object:
          type: string
          enum:
            - admin_role
          description: Object type identifier
          example: admin_role
        id:
          type: string
          description: Role unique identifier
          example: 6648f22b7b23fb2f4307aafe
        name:
          type: string
          description: Role name
          example: Admin
        permissions:
          $ref: '#/components/schemas/AdminRolePermissions'
      required:
        - object
        - id
        - name
        - permissions
    AdminRoleList:
      type: object
      properties:
        object:
          type: string
          enum:
            - list
          description: Object type identifier
          example: list
        data:
          type: array
          items:
            $ref: '#/components/schemas/AdminRole'
          description: Array of admin roles
          example: []
        nextCursor:
          type:
            - string
            - 'null'
          description: Cursor for fetching the next page (cursor-based pagination)
          example: null
      required:
        - object
        - data
        - nextCursor
    CustomFieldOption:
      type: object
      properties:
        id:
          type: string
          description: Option unique identifier
          example: 65d26304b2e65b1e1278170d
        label:
          type: string
          description: Option display label
          example: High Priority
      required:
        - id
        - label
    CustomField:
      type: object
      properties:
        object:
          type: string
          enum:
            - custom_field
          description: Object type identifier
          example: custom_field
        id:
          type: string
          description: Unique identifier
          example: 65d26304b2e65b1e1278170c
        label:
          type: string
          description: Field label displayed to users
          example: Your @username
        type:
          type: string
          enum:
            - text
            - number
            - select
            - multi-select
            - checkbox
            - date
          description: Field type
          example: text
        required:
          type: boolean
          description: Whether the field is required
          example: true
        placeholder:
          type: string
          description: Placeholder text
          example: Enter your username
        public:
          type: boolean
          description: Whether the field value is publicly visible
          example: false
        internal:
          type: boolean
          description: Whether the field is for internal use only
          example: false
        options:
          type: array
          items:
            $ref: '#/components/schemas/CustomFieldOption'
          description: Options for select/multi-select fields
          example:
            - id: 65d26304b2e65b1e1278170d
              label: High Priority
        createdAt:
          type: string
          description: ISO timestamp when created
          example: '2025-04-06T14:11:58.141Z'
        updatedAt:
          type: string
          description: ISO timestamp when last updated
          example: '2025-04-06T14:11:58.141Z'
      required:
        - object
        - id
        - label
        - type
    CustomFieldList:
      type: object
      properties:
        object:
          type: string
          enum:
            - list
          description: Object type identifier
          example: list
        data:
          type: array
          items:
            $ref: '#/components/schemas/CustomField'
          description: Array of custom fields
          example: []
        nextCursor:
          type:
            - string
            - 'null'
          description: Cursor for fetching the next page (cursor-based pagination)
          example: null
        pagination:
          type: object
          properties:
            page:
              type: number
              description: Current page number
              example: 1
            limit:
              type: number
              description: Items per page
              example: 10
            total:
              type: number
              description: Total number of items
              example: 42
            totalPages:
              type: number
              description: Total number of pages
              example: 5
          required:
            - page
            - limit
            - total
            - totalPages
          description: Pagination metadata for page-based requests
      required:
        - object
        - data
        - nextCursor
    SurveyUrlTargeting:
      type: object
      properties:
        value:
          type: string
          description: URL pattern to match
          example: /dashboard/posts
        matchType:
          type: string
          enum:
            - exact
            - contains
            - regex
          description: Type of URL matching
          example: contains
        id:
          type: string
          description: Rule ID
          example: 674375cfd8bf964ec2562cdc
      required:
        - value
        - matchType
    SurveyCssTargeting:
      type: object
      properties:
        value:
          type: string
          description: CSS selector
          example: .feedback-button
      required:
        - value
    SurveyTargeting:
      type: object
      properties:
        segmentIds:
          type: array
          items:
            type: string
          description: Segment IDs to target
          example:
            - 6636438b7fcdc515999042eb
        url:
          type: array
          items:
            $ref: '#/components/schemas/SurveyUrlTargeting'
          description: URL targeting rules
        css:
          type: array
          items:
            $ref: '#/components/schemas/SurveyCssTargeting'
          description: CSS selector targeting rules
        loginRequired:
          type: boolean
          description: Whether login is required
          example: false
      description: Targeting configuration
    SurveyChoice:
      type: object
      properties:
        id:
          type: string
          description: Choice ID
          example: 66dc54128b989696d050008b
        choice:
          type: string
          description: Choice text
          example: Very satisfied
      required:
        - id
    SurveyNextAction:
      type: object
      properties:
        type:
          type: string
          enum:
            - page
            - end
            - next
          description: Type of next action
          example: page
        pageId:
          type: string
          description: Page ID to navigate to
          example: 6743754dd8bf964ec2562cda
      required:
        - type
      description: Action to take if condition matches
    SurveyPageLogic:
      type: object
      properties:
        id:
          type: string
          description: Logic rule ID
          example: 6743755fd8bf964ec2562cdb
        comparator:
          type: string
          description: Comparison operator
          example: less than
        value:
          anyOf:
            - type: string
            - type: number
            - type: array
              items:
                type: string
          description: Value to compare against
          example: 4
        next:
          $ref: '#/components/schemas/SurveyNextAction'
      required:
        - comparator
        - value
        - next
    SurveyPage:
      type: object
      properties:
        id:
          type: string
          description: Page ID
          example: 6743752ca81ae59d25cf834c
        type:
          type: string
          enum:
            - text
            - link
            - rating
            - multiple-choice
          description: Page type
          example: rating
        title:
          type: string
          description: Page title
          example: How happy are you with our product?
        description:
          type: string
          description: Page description
          example: We really want to hear from you.
        placeholder:
          type: string
          description: Placeholder for text input
          example: Type your answer here
        linkButtonText:
          type: string
          description: Button text for link
          example: Visit our website
        linkRedirectUrl:
          type: string
          description: URL to redirect to
          example: https://example.com
        linkTarget:
          type: string
          enum:
            - _blank
            - _self
            - _parent
            - _top
          description: Link target
          example: _blank
        subType:
          type: string
          enum:
            - number
            - emoji
            - generic
            - featurebase-posts
            - nps
          description: Sub-type for rating/multiple-choice
          example: emoji
        scale:
          type: number
          description: Rating scale
          example: 5
        lowLabel:
          type: string
          description: Label for low rating
          example: Could be improved
        highLabel:
          type: string
          description: Label for high rating
          example: It's awesome!
        allowSelectMultiple:
          type: boolean
          description: Allow multiple selections
          example: false
        choices:
          type: array
          items:
            $ref: '#/components/schemas/SurveyChoice'
          description: Available choices
        logic:
          type: array
          items:
            $ref: '#/components/schemas/SurveyPageLogic'
          description: Conditional logic rules
        defaultAction:
          allOf:
            - $ref: '#/components/schemas/SurveyNextAction'
            - description: Default action if no logic matches
      required:
        - id
        - type
        - title
    Survey:
      type: object
      properties:
        object:
          type: string
          enum:
            - survey
          description: Object type identifier
          example: survey
        id:
          type: string
          description: Unique identifier
          example: 6743752ca81ae59d25cf834b
        title:
          type: string
          description: Survey title
          example: Get feedback for Feedback module
        description:
          type: string
          description: Survey description
          example: Measure what we can improve
        isActive:
          type: boolean
          description: Whether the survey is active
          example: true
        organization:
          type: string
          description: Organization ID
          example: 5febde12dc56d60012d47db6
        responseCount:
          type: number
          description: Number of responses
          example: 85
        targeting:
          $ref: '#/components/schemas/SurveyTargeting'
        pages:
          type: array
          items:
            $ref: '#/components/schemas/SurveyPage'
          description: Survey pages
          example: []
        createdAt:
          type: string
          description: ISO 8601 timestamp when created
          example: '2024-11-24T18:49:16.755Z'
        updatedAt:
          type: string
          description: ISO 8601 timestamp when last updated
          example: '2025-04-10T08:58:51.148Z'
      required:
        - object
        - id
        - title
        - isActive
        - organization
        - responseCount
        - pages
        - createdAt
        - updatedAt
    SurveyList:
      type: object
      properties:
        object:
          type: string
          enum:
            - list
          description: Object type identifier
          example: list
        data:
          type: array
          items:
            $ref: '#/components/schemas/Survey'
          description: Array of surveys
          example: []
        nextCursor:
          type:
            - string
            - 'null'
          description: Cursor for fetching the next page (cursor-based pagination)
          example: null
      required:
        - object
        - data
        - nextCursor
    Contact:
      type:
        - object
        - 'null'
      properties:
        object:
          type: string
          enum:
            - contact
          description: Object type identifier
          example: contact
        id:
          type: string
          description: Unique identifier
          example: 676f0f6765bdaa7d7d760f88
        userId:
          type: string
          description: External user ID from SSO
          example: 676f0f673dbb299c8a4f3057
        organizationId:
          type: string
          description: Organization ID the contact belongs to
          example: 5febde12dc56d60012d47db6
        companies:
          type: array
          items:
            $ref: '#/components/schemas/Company'
          description: Companies the contact belongs to
          example: []
        email:
          type:
            - string
            - 'null'
          description: Contact email
          example: john@example.com
        name:
          type: string
          description: Contact display name
          example: John Steezy
        profilePicture:
          type:
            - string
            - 'null'
          description: Profile picture URL
          example: https://fb-usercontent.fra1.cdn.digitaloceanspaces.com/anon_23.png
        commentsCreated:
          type: number
          description: Number of comments created
          example: 0
        postsCreated:
          type: number
          description: Number of posts created
          example: 0
        lastActivity:
          type: string
          description: Last activity ISO timestamp
          example: '2025-01-03T21:42:30.181Z'
        subscribedToChangelog:
          type: boolean
          description: Whether subscribed to changelog
          example: true
        manuallyOptedOutFromChangelog:
          type: boolean
          description: Whether manually opted out from changelog
          example: false
        roles:
          type: array
          items:
            type: string
          description: Contact roles
          example: []
        locale:
          type: string
          description: Contact locale
          example: en
        verified:
          type: boolean
          description: Whether email is verified
          example: true
        type:
          type: string
          enum:
            - customer
            - lead
          description: Type of contact
          example: customer
        description:
          type: string
          description: Contact description/bio
          example: ''
        customFields:
          type: object
          additionalProperties: {}
          description: Custom field values on the contact
      required:
        - object
        - id
        - name
        - type
      description: User who submitted the response
    SurveySingleResponse:
      type: object
      properties:
        pageId:
          type: string
          description: Page ID this response is for
          example: 66dc53c5a64824f0e84a4c1e
        type:
          type: string
          enum:
            - text
            - link
            - rating
            - multiple-choice
          description: Response type
          example: multiple-choice
        value:
          anyOf:
            - type: string
            - type: number
            - type: boolean
            - type: array
              items:
                type: string
          description: Response value
          example:
            - 66dc54128b989696d050008b
        id:
          type: string
          description: Response ID
          example: 6712e2d175904ce24b2f9638
        createdAt:
          type: string
          description: ISO 8601 timestamp when created
          example: '2024-10-18T22:36:01.270Z'
        updatedAt:
          type: string
          description: ISO 8601 timestamp when updated
          example: '2024-10-18T22:36:01.270Z'
      required:
        - pageId
        - type
        - value
    SurveyResponse:
      type: object
      properties:
        object:
          type: string
          enum:
            - survey_response
          description: Object type identifier
          example: survey_response
        id:
          type: string
          description: Unique identifier
          example: 6712e2d175904ce24b2f9637
        user:
          $ref: '#/components/schemas/Contact'
        responses:
          type: array
          items:
            $ref: '#/components/schemas/SurveySingleResponse'
          description: Individual responses to questions
          example: []
        createdAt:
          type: string
          description: ISO 8601 timestamp when created
          example: '2024-10-18T22:36:01.269Z'
      required:
        - object
        - id
        - user
        - responses
        - createdAt
    SurveyResponseList:
      type: object
      properties:
        object:
          type: string
          enum:
            - list
          description: Object type identifier
          example: list
        data:
          type: array
          items:
            $ref: '#/components/schemas/SurveyResponse'
          description: Array of survey responses
          example: []
        nextCursor:
          type:
            - string
            - 'null'
          description: Cursor for fetching the next page (cursor-based pagination)
          example: null
      required:
        - object
        - data
        - nextCursor
    HelpCenterNavItem:
      type: object
      properties:
        type:
          type: string
          enum:
            - link
            - button
          description: Navigation item type
          example: link
        title:
          type: string
          description: Navigation item title
          example: Developer Docs
        url:
          type: string
          description: Navigation item URL
          example: https://developers.featurebase.app/install
        icon:
          type:
            - string
            - 'null'
          description: Navigation item icon
          example: null
      required:
        - type
        - title
        - url
    HelpCenterUrls:
      type: object
      properties:
        featurebaseSubpath:
          type: string
          description: Featurebase subpath
          example: /help
        externalDomain:
          type: string
          description: External custom domain
          example: help.example.com
      description: URLs configuration
    HelpCenterTranslation:
      type: object
      properties:
        displayName:
          type: string
          description: Display name for this locale
          example: My English Help Center
        title:
          type: string
          description: Title for this locale
          example: Help Center
        description:
          type: string
          description: Description for this locale
          example: Find answers to common questions
        searchPlaceholder:
          type: string
          description: Search placeholder for this locale
          example: Search articles...
        navItems:
          type: array
          items:
            $ref: '#/components/schemas/HelpCenterNavItem'
          description: Navigation items for this locale
    HelpCenter:
      type: object
      properties:
        object:
          type: string
          enum:
            - help_center
          description: Object type identifier
          example: help_center
        id:
          type: string
          description: Help center unique identifier
          example: 2tgy0ig982j54qfl
        displayName:
          type: string
          description: Help center display name
          example: Your Help Center
        title:
          type: string
          description: Help center title
          example: Help Center
        description:
          type: string
          description: Help center description
          example: ''
        searchPlaceholder:
          type: string
          description: Search input placeholder
          example: Search for help...
        isPublic:
          type: boolean
          description: Whether the help center is public
          example: true
        hideAuthorInfo:
          type: boolean
          description: Whether to hide author info on articles
          example: false
        hideDateInfo:
          type: boolean
          description: Whether to hide date info on articles
          example: false
        externalLinksOpenInNewTab:
          type: boolean
          description: Whether external links in articles open in a new tab
          example: true
        internalLinksOpenInNewTab:
          type: boolean
          description: Whether internal links in articles open in a new tab
          example: false
        defaultLocale:
          type: string
          enum:
            - bn
            - bs
            - pt-BR
            - bg
            - ca
            - hr
            - cs
            - da
            - nl
            - en
            - et
            - fi
            - fr
            - de
            - el
            - hi
            - hu
            - id
            - it
            - ja
            - ko
            - lv
            - lt
            - ms
            - mn
            - nb
            - pl
            - pt
            - ro
            - ru
            - sr
            - zh-CN
            - sk
            - sl
            - es
            - sw
            - sv
            - th
            - zh-TW
            - tr
            - uk
            - vi
          description: Default locale for the help center
          example: en
        locale:
          type: string
          enum:
            - bn
            - bs
            - pt-BR
            - bg
            - ca
            - hr
            - cs
            - da
            - nl
            - en
            - et
            - fi
            - fr
            - de
            - el
            - hi
            - hu
            - id
            - it
            - ja
            - ko
            - lv
            - lt
            - ms
            - mn
            - nb
            - pl
            - pt
            - ro
            - ru
            - sr
            - zh-CN
            - sk
            - sl
            - es
            - sw
            - sv
            - th
            - zh-TW
            - tr
            - uk
            - vi
          description: Current locale
          example: en
        availableLocales:
          type: array
          items:
            type: string
            enum:
              - bn
              - bs
              - pt-BR
              - bg
              - ca
              - hr
              - cs
              - da
              - nl
              - en
              - et
              - fi
              - fr
              - de
              - el
              - hi
              - hu
              - id
              - it
              - ja
              - ko
              - lv
              - lt
              - ms
              - mn
              - nb
              - pl
              - pt
              - ro
              - ru
              - sr
              - zh-CN
              - sk
              - sl
              - es
              - sw
              - sv
              - th
              - zh-TW
              - tr
              - uk
              - vi
            description: Locale code for localized content
            example: en
          description: Available locales
          example:
            - en
        navItems:
          type: array
          items:
            $ref: '#/components/schemas/HelpCenterNavItem'
          description: Navigation items
        urls:
          $ref: '#/components/schemas/HelpCenterUrls'
        translations:
          type: object
          properties:
            bn:
              $ref: '#/components/schemas/HelpCenterTranslation'
            bs:
              $ref: '#/components/schemas/HelpCenterTranslation'
            pt-BR:
              $ref: '#/components/schemas/HelpCenterTranslation'
            bg:
              $ref: '#/components/schemas/HelpCenterTranslation'
            ca:
              $ref: '#/components/schemas/HelpCenterTranslation'
            hr:
              $ref: '#/components/schemas/HelpCenterTranslation'
            cs:
              $ref: '#/components/schemas/HelpCenterTranslation'
            da:
              $ref: '#/components/schemas/HelpCenterTranslation'
            nl:
              $ref: '#/components/schemas/HelpCenterTranslation'
            en:
              $ref: '#/components/schemas/HelpCenterTranslation'
            et:
              $ref: '#/components/schemas/HelpCenterTranslation'
            fi:
              $ref: '#/components/schemas/HelpCenterTranslation'
            fr:
              $ref: '#/components/schemas/HelpCenterTranslation'
            de:
              $ref: '#/components/schemas/HelpCenterTranslation'
            el:
              $ref: '#/components/schemas/HelpCenterTranslation'
            hi:
              $ref: '#/components/schemas/HelpCenterTranslation'
            hu:
              $ref: '#/components/schemas/HelpCenterTranslation'
            id:
              $ref: '#/components/schemas/HelpCenterTranslation'
            it:
              $ref: '#/components/schemas/HelpCenterTranslation'
            ja:
              $ref: '#/components/schemas/HelpCenterTranslation'
            ko:
              $ref: '#/components/schemas/HelpCenterTranslation'
            lv:
              $ref: '#/components/schemas/HelpCenterTranslation'
            lt:
              $ref: '#/components/schemas/HelpCenterTranslation'
            ms:
              $ref: '#/components/schemas/HelpCenterTranslation'
            mn:
              $ref: '#/components/schemas/HelpCenterTranslation'
            nb:
              $ref: '#/components/schemas/HelpCenterTranslation'
            pl:
              $ref: '#/components/schemas/HelpCenterTranslation'
            pt:
              $ref: '#/components/schemas/HelpCenterTranslation'
            ro:
              $ref: '#/components/schemas/HelpCenterTranslation'
            ru:
              $ref: '#/components/schemas/HelpCenterTranslation'
            sr:
              $ref: '#/components/schemas/HelpCenterTranslation'
            zh-CN:
              $ref: '#/components/schemas/HelpCenterTranslation'
            sk:
              $ref: '#/components/schemas/HelpCenterTranslation'
            sl:
              $ref: '#/components/schemas/HelpCenterTranslation'
            es:
              $ref: '#/components/schemas/HelpCenterTranslation'
            sw:
              $ref: '#/components/schemas/HelpCenterTranslation'
            sv:
              $ref: '#/components/schemas/HelpCenterTranslation'
            th:
              $ref: '#/components/schemas/HelpCenterTranslation'
            zh-TW:
              $ref: '#/components/schemas/HelpCenterTranslation'
            tr:
              $ref: '#/components/schemas/HelpCenterTranslation'
            uk:
              $ref: '#/components/schemas/HelpCenterTranslation'
            vi:
              $ref: '#/components/schemas/HelpCenterTranslation'
          description: Translations for different locales
        organization:
          type: string
          description: Organization ID
          example: 6595518396205e06b897ad65
        createdAt:
          type: string
          description: ISO 8601 timestamp when created
          example: '2024-06-26T13:27:21.920Z'
        updatedAt:
          type: string
          description: ISO 8601 timestamp when last updated
          example: '2024-06-26T13:52:19.415Z'
      required:
        - object
        - id
        - isPublic
        - defaultLocale
        - locale
        - availableLocales
        - organization
        - createdAt
        - updatedAt
    HelpCenterList:
      type: object
      properties:
        object:
          type: string
          enum:
            - list
          description: Object type identifier
          example: list
        data:
          type: array
          items:
            $ref: '#/components/schemas/HelpCenter'
          description: Array of help centers
          example: []
        nextCursor:
          type:
            - string
            - 'null'
          description: Cursor for fetching the next page (cursor-based pagination)
          example: null
      required:
        - object
        - data
        - nextCursor
    CollectionIcon:
      type:
        - object
        - 'null'
      properties:
        type:
          type: string
          description: Icon type
          example: emoji
        value:
          type: string
          description: Icon value
          example: 🥾
      required:
        - type
        - value
      description: Collection icon
    CollectionAuthor:
      type: object
      properties:
        name:
          type: string
          description: Author name
          example: John Doe
        authorId:
          type: string
          description: Author ID
          example: 507f1f77bcf86cd799439011
        avatarUrl:
          type:
            - string
            - 'null'
          description: Author avatar URL
          example: https://example.com/avatar.png
    CollectionTranslation:
      type: object
      properties:
        name:
          type: string
          description: Collection name
          example: English Collection
        description:
          type: string
          description: Collection description
          example: A collection of articles
        slug:
          type: string
          description: URL slug
          example: 3416135-english-collection
        featurebaseUrl:
          type: string
          description: Featurebase URL
          example: >-
            https://yourorg.featurebase.app/en/help/collections/3416135-english-collection
        externalUrl:
          type: string
          description: External URL
          example: >-
            https://help.yourdomain.com/en/collections/3416135-english-collection
        articleCount:
          type: number
          description: Number of articles
          example: 15
        authorCount:
          type: number
          description: Number of authors
          example: 3
        authors:
          type: array
          items:
            $ref: '#/components/schemas/CollectionAuthor'
          description: List of authors
    Collection:
      type: object
      properties:
        object:
          type: string
          enum:
            - collection
          description: Object type identifier
          example: collection
        id:
          type: string
          description: Collection unique identifier
          example: '6474684'
        name:
          type: string
          description: Collection name
          example: English Collection Name
        description:
          type: string
          description: Collection description
          example: A description in English
        slug:
          type: string
          description: URL slug
          example: 6474684-english-version
        icon:
          $ref: '#/components/schemas/CollectionIcon'
        parentId:
          type:
            - string
            - 'null'
          description: Parent collection ID
          example: null
        helpCenterId:
          type: string
          description: Help center ID
          example: j7c5g8ah3ewxp4lo
        organization:
          type: string
          description: Organization ID
          example: 6595518396205e06b897ad65
        defaultLocale:
          type: string
          enum:
            - bn
            - bs
            - pt-BR
            - bg
            - ca
            - hr
            - cs
            - da
            - nl
            - en
            - et
            - fi
            - fr
            - de
            - el
            - hi
            - hu
            - id
            - it
            - ja
            - ko
            - lv
            - lt
            - ms
            - mn
            - nb
            - pl
            - pt
            - ro
            - ru
            - sr
            - zh-CN
            - sk
            - sl
            - es
            - sw
            - sv
            - th
            - zh-TW
            - tr
            - uk
            - vi
          description: Default locale
          example: en
        locale:
          type: string
          enum:
            - bn
            - bs
            - pt-BR
            - bg
            - ca
            - hr
            - cs
            - da
            - nl
            - en
            - et
            - fi
            - fr
            - de
            - el
            - hi
            - hu
            - id
            - it
            - ja
            - ko
            - lv
            - lt
            - ms
            - mn
            - nb
            - pl
            - pt
            - ro
            - ru
            - sr
            - zh-CN
            - sk
            - sl
            - es
            - sw
            - sv
            - th
            - zh-TW
            - tr
            - uk
            - vi
          description: Current locale
          example: en
        availableLocales:
          type: array
          items:
            type: string
            enum:
              - bn
              - bs
              - pt-BR
              - bg
              - ca
              - hr
              - cs
              - da
              - nl
              - en
              - et
              - fi
              - fr
              - de
              - el
              - hi
              - hu
              - id
              - it
              - ja
              - ko
              - lv
              - lt
              - ms
              - mn
              - nb
              - pl
              - pt
              - ro
              - ru
              - sr
              - zh-CN
              - sk
              - sl
              - es
              - sw
              - sv
              - th
              - zh-TW
              - tr
              - uk
              - vi
            description: Locale code for localized content
            example: en
          description: Available locales
          example:
            - en
            - de
        featurebaseUrl:
          type: string
          description: Featurebase URL
          example: >-
            https://yourorg.featurebase.app/en/help/collections/6474684-english-version
        externalUrl:
          type: string
          description: External URL
          example: https://help.yourdomain.com/en/collections/6474684-english-version
        articleCount:
          type: number
          description: Number of articles
          example: 15
        authorCount:
          type: number
          description: Number of authors
          example: 3
        order:
          type:
            - number
            - 'null'
          description: Display order
          example: 1
        path:
          type: string
          description: Collection path
          example: ox6qrqprmsuqaunj/3876752/3513543
        collapseSidebar:
          type: boolean
          description: Whether to collapse sidebar
          example: false
        translations:
          type: object
          properties:
            bn:
              $ref: '#/components/schemas/CollectionTranslation'
            bs:
              $ref: '#/components/schemas/CollectionTranslation'
            pt-BR:
              $ref: '#/components/schemas/CollectionTranslation'
            bg:
              $ref: '#/components/schemas/CollectionTranslation'
            ca:
              $ref: '#/components/schemas/CollectionTranslation'
            hr:
              $ref: '#/components/schemas/CollectionTranslation'
            cs:
              $ref: '#/components/schemas/CollectionTranslation'
            da:
              $ref: '#/components/schemas/CollectionTranslation'
            nl:
              $ref: '#/components/schemas/CollectionTranslation'
            en:
              $ref: '#/components/schemas/CollectionTranslation'
            et:
              $ref: '#/components/schemas/CollectionTranslation'
            fi:
              $ref: '#/components/schemas/CollectionTranslation'
            fr:
              $ref: '#/components/schemas/CollectionTranslation'
            de:
              $ref: '#/components/schemas/CollectionTranslation'
            el:
              $ref: '#/components/schemas/CollectionTranslation'
            hi:
              $ref: '#/components/schemas/CollectionTranslation'
            hu:
              $ref: '#/components/schemas/CollectionTranslation'
            id:
              $ref: '#/components/schemas/CollectionTranslation'
            it:
              $ref: '#/components/schemas/CollectionTranslation'
            ja:
              $ref: '#/components/schemas/CollectionTranslation'
            ko:
              $ref: '#/components/schemas/CollectionTranslation'
            lv:
              $ref: '#/components/schemas/CollectionTranslation'
            lt:
              $ref: '#/components/schemas/CollectionTranslation'
            ms:
              $ref: '#/components/schemas/CollectionTranslation'
            mn:
              $ref: '#/components/schemas/CollectionTranslation'
            nb:
              $ref: '#/components/schemas/CollectionTranslation'
            pl:
              $ref: '#/components/schemas/CollectionTranslation'
            pt:
              $ref: '#/components/schemas/CollectionTranslation'
            ro:
              $ref: '#/components/schemas/CollectionTranslation'
            ru:
              $ref: '#/components/schemas/CollectionTranslation'
            sr:
              $ref: '#/components/schemas/CollectionTranslation'
            zh-CN:
              $ref: '#/components/schemas/CollectionTranslation'
            sk:
              $ref: '#/components/schemas/CollectionTranslation'
            sl:
              $ref: '#/components/schemas/CollectionTranslation'
            es:
              $ref: '#/components/schemas/CollectionTranslation'
            sw:
              $ref: '#/components/schemas/CollectionTranslation'
            sv:
              $ref: '#/components/schemas/CollectionTranslation'
            th:
              $ref: '#/components/schemas/CollectionTranslation'
            zh-TW:
              $ref: '#/components/schemas/CollectionTranslation'
            tr:
              $ref: '#/components/schemas/CollectionTranslation'
            uk:
              $ref: '#/components/schemas/CollectionTranslation'
            vi:
              $ref: '#/components/schemas/CollectionTranslation'
          description: Translations by locale code
        createdAt:
          type: string
          description: ISO 8601 timestamp when created
          example: '2024-10-18T12:33:09.099Z'
        updatedAt:
          type: string
          description: ISO 8601 timestamp when last updated
          example: '2024-10-18T13:03:25.921Z'
      required:
        - object
        - id
        - parentId
        - helpCenterId
        - organization
        - locale
        - availableLocales
        - createdAt
        - updatedAt
    CollectionList:
      type: object
      properties:
        object:
          type: string
          enum:
            - list
          description: Object type identifier
          example: list
        data:
          type: array
          items:
            $ref: '#/components/schemas/Collection'
          description: Array of collections
          example: []
        nextCursor:
          type:
            - string
            - 'null'
          description: Cursor for fetching the next page (cursor-based pagination)
          example: null
      required:
        - object
        - data
        - nextCursor
    CollectionIcon_Nova:
      type:
        - object
        - 'null'
      properties:
        type:
          type: string
          enum:
            - emoji
            - predefined
          description: Icon type (e.g., "emoji")
          example: emoji
        value:
          type: string
          maxLength: 255
          description: Icon value
          example: 📝
      required:
        - type
        - value
      description: An updated icon object for the collection
    CollectionTranslationInput_Nova:
      type: object
      properties:
        name:
          type: string
          maxLength: 255
          description: Collection name in this locale
          example: German Collection
        description:
          type: string
          maxLength: 512
          description: Collection description in this locale
          example: This is a collection of articles in German.
    UpdateCollectionBody_Nova:
      type: object
      properties:
        name:
          type: string
          maxLength: 255
          description: The new name of the collection
          example: Updated Collection
        description:
          type: string
          maxLength: 512
          description: The new description of the collection
          example: Updated description in English.
        icon:
          $ref: '#/components/schemas/CollectionIcon_Nova'
        parentId:
          type:
            - string
            - 'null'
          minLength: 1
          maxLength: 16
          pattern: ^[a-zA-Z0-9]+$
          description: The new parent collection ID, if applicable
          example: null
        translations:
          type: object
          properties:
            bn:
              $ref: '#/components/schemas/CollectionTranslationInput_Nova'
            bs:
              $ref: '#/components/schemas/CollectionTranslationInput_Nova'
            pt-BR:
              $ref: '#/components/schemas/CollectionTranslationInput_Nova'
            bg:
              $ref: '#/components/schemas/CollectionTranslationInput_Nova'
            ca:
              $ref: '#/components/schemas/CollectionTranslationInput_Nova'
            hr:
              $ref: '#/components/schemas/CollectionTranslationInput_Nova'
            cs:
              $ref: '#/components/schemas/CollectionTranslationInput_Nova'
            da:
              $ref: '#/components/schemas/CollectionTranslationInput_Nova'
            nl:
              $ref: '#/components/schemas/CollectionTranslationInput_Nova'
            en:
              $ref: '#/components/schemas/CollectionTranslationInput_Nova'
            et:
              $ref: '#/components/schemas/CollectionTranslationInput_Nova'
            fi:
              $ref: '#/components/schemas/CollectionTranslationInput_Nova'
            fr:
              $ref: '#/components/schemas/CollectionTranslationInput_Nova'
            de:
              $ref: '#/components/schemas/CollectionTranslationInput_Nova'
            el:
              $ref: '#/components/schemas/CollectionTranslationInput_Nova'
            hi:
              $ref: '#/components/schemas/CollectionTranslationInput_Nova'
            hu:
              $ref: '#/components/schemas/CollectionTranslationInput_Nova'
            id:
              $ref: '#/components/schemas/CollectionTranslationInput_Nova'
            it:
              $ref: '#/components/schemas/CollectionTranslationInput_Nova'
            ja:
              $ref: '#/components/schemas/CollectionTranslationInput_Nova'
            ko:
              $ref: '#/components/schemas/CollectionTranslationInput_Nova'
            lv:
              $ref: '#/components/schemas/CollectionTranslationInput_Nova'
            lt:
              $ref: '#/components/schemas/CollectionTranslationInput_Nova'
            ms:
              $ref: '#/components/schemas/CollectionTranslationInput_Nova'
            mn:
              $ref: '#/components/schemas/CollectionTranslationInput_Nova'
            nb:
              $ref: '#/components/schemas/CollectionTranslationInput_Nova'
            pl:
              $ref: '#/components/schemas/CollectionTranslationInput_Nova'
            pt:
              $ref: '#/components/schemas/CollectionTranslationInput_Nova'
            ro:
              $ref: '#/components/schemas/CollectionTranslationInput_Nova'
            ru:
              $ref: '#/components/schemas/CollectionTranslationInput_Nova'
            sr:
              $ref: '#/components/schemas/CollectionTranslationInput_Nova'
            zh-CN:
              $ref: '#/components/schemas/CollectionTranslationInput_Nova'
            sk:
              $ref: '#/components/schemas/CollectionTranslationInput_Nova'
            sl:
              $ref: '#/components/schemas/CollectionTranslationInput_Nova'
            es:
              $ref: '#/components/schemas/CollectionTranslationInput_Nova'
            sw:
              $ref: '#/components/schemas/CollectionTranslationInput_Nova'
            sv:
              $ref: '#/components/schemas/CollectionTranslationInput_Nova'
            th:
              $ref: '#/components/schemas/CollectionTranslationInput_Nova'
            zh-TW:
              $ref: '#/components/schemas/CollectionTranslationInput_Nova'
            tr:
              $ref: '#/components/schemas/CollectionTranslationInput_Nova'
            uk:
              $ref: '#/components/schemas/CollectionTranslationInput_Nova'
            vi:
              $ref: '#/components/schemas/CollectionTranslationInput_Nova'
          description: A dictionary of updated translations keyed by locale
      additionalProperties: false
    CreateCollectionBody_Nova:
      type: object
      properties:
        name:
          type: string
          maxLength: 255
          description: The name of the collection
          example: English Collection
        description:
          type: string
          maxLength: 512
          description: A description of the collection
          example: This is a collection of articles in English.
        icon:
          allOf:
            - $ref: '#/components/schemas/CollectionIcon_Nova'
            - description: An icon object representing the collection icon
        parentId:
          type:
            - string
            - 'null'
          minLength: 1
          maxLength: 16
          pattern: ^[a-zA-Z0-9]+$
          description: The ID of the parent collection, if any
          example: null
        translations:
          type: object
          properties:
            bn:
              $ref: '#/components/schemas/CollectionTranslationInput_Nova'
            bs:
              $ref: '#/components/schemas/CollectionTranslationInput_Nova'
            pt-BR:
              $ref: '#/components/schemas/CollectionTranslationInput_Nova'
            bg:
              $ref: '#/components/schemas/CollectionTranslationInput_Nova'
            ca:
              $ref: '#/components/schemas/CollectionTranslationInput_Nova'
            hr:
              $ref: '#/components/schemas/CollectionTranslationInput_Nova'
            cs:
              $ref: '#/components/schemas/CollectionTranslationInput_Nova'
            da:
              $ref: '#/components/schemas/CollectionTranslationInput_Nova'
            nl:
              $ref: '#/components/schemas/CollectionTranslationInput_Nova'
            en:
              $ref: '#/components/schemas/CollectionTranslationInput_Nova'
            et:
              $ref: '#/components/schemas/CollectionTranslationInput_Nova'
            fi:
              $ref: '#/components/schemas/CollectionTranslationInput_Nova'
            fr:
              $ref: '#/components/schemas/CollectionTranslationInput_Nova'
            de:
              $ref: '#/components/schemas/CollectionTranslationInput_Nova'
            el:
              $ref: '#/components/schemas/CollectionTranslationInput_Nova'
            hi:
              $ref: '#/components/schemas/CollectionTranslationInput_Nova'
            hu:
              $ref: '#/components/schemas/CollectionTranslationInput_Nova'
            id:
              $ref: '#/components/schemas/CollectionTranslationInput_Nova'
            it:
              $ref: '#/components/schemas/CollectionTranslationInput_Nova'
            ja:
              $ref: '#/components/schemas/CollectionTranslationInput_Nova'
            ko:
              $ref: '#/components/schemas/CollectionTranslationInput_Nova'
            lv:
              $ref: '#/components/schemas/CollectionTranslationInput_Nova'
            lt:
              $ref: '#/components/schemas/CollectionTranslationInput_Nova'
            ms:
              $ref: '#/components/schemas/CollectionTranslationInput_Nova'
            mn:
              $ref: '#/components/schemas/CollectionTranslationInput_Nova'
            nb:
              $ref: '#/components/schemas/CollectionTranslationInput_Nova'
            pl:
              $ref: '#/components/schemas/CollectionTranslationInput_Nova'
            pt:
              $ref: '#/components/schemas/CollectionTranslationInput_Nova'
            ro:
              $ref: '#/components/schemas/CollectionTranslationInput_Nova'
            ru:
              $ref: '#/components/schemas/CollectionTranslationInput_Nova'
            sr:
              $ref: '#/components/schemas/CollectionTranslationInput_Nova'
            zh-CN:
              $ref: '#/components/schemas/CollectionTranslationInput_Nova'
            sk:
              $ref: '#/components/schemas/CollectionTranslationInput_Nova'
            sl:
              $ref: '#/components/schemas/CollectionTranslationInput_Nova'
            es:
              $ref: '#/components/schemas/CollectionTranslationInput_Nova'
            sw:
              $ref: '#/components/schemas/CollectionTranslationInput_Nova'
            sv:
              $ref: '#/components/schemas/CollectionTranslationInput_Nova'
            th:
              $ref: '#/components/schemas/CollectionTranslationInput_Nova'
            zh-TW:
              $ref: '#/components/schemas/CollectionTranslationInput_Nova'
            tr:
              $ref: '#/components/schemas/CollectionTranslationInput_Nova'
            uk:
              $ref: '#/components/schemas/CollectionTranslationInput_Nova'
            vi:
              $ref: '#/components/schemas/CollectionTranslationInput_Nova'
          description: A dictionary of translations keyed by locale
      required:
        - name
      additionalProperties: false
    DeletedCollection:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier of the deleted collection
          example: '3416135'
        object:
          type: string
          enum:
            - collection
          description: Object type identifier
          example: collection
        deleted:
          type: boolean
          enum:
            - true
          description: Indicates the resource was deleted
          example: true
      required:
        - id
        - object
        - deleted
    ArticleIcon:
      type:
        - object
        - 'null'
      properties:
        type:
          type: string
          enum:
            - emoji
            - custom
          description: Icon type
          example: emoji
        value:
          type: string
          description: Icon value (emoji or URL)
          example: 📖
      required:
        - type
        - value
      description: Article icon
    ArticleAuthor:
      type: object
      properties:
        name:
          type: string
          description: Author name
          example: John Doe
        authorId:
          type: string
          description: Author user ID
          example: 507f1f77bcf86cd799439011
        avatarUrl:
          type:
            - string
            - 'null'
          description: Author avatar URL
          example: null
      required:
        - name
        - authorId
      description: Article author
    ArticleTranslation:
      type: object
      properties:
        title:
          type: string
          description: Article title
          example: Getting Started Guide
        description:
          type: string
          description: Article description
          example: Learn how to get started
        body:
          type: string
          description: Article body content (HTML)
          example: <p>Welcome to our guide.</p>
        slug:
          type: string
          description: URL slug
          example: 1234567-getting-started-guide
        featurebaseUrl:
          type: string
          description: Featurebase URL
          example: >-
            https://yourorg.featurebase.app/en/help/articles/1234567-getting-started-guide
        externalUrl:
          type: string
          description: External URL
          example: >-
            https://help.yourdomain.com/en/articles/1234567-getting-started-guide
        author:
          allOf:
            - $ref: '#/components/schemas/ArticleAuthor'
            - description: Article author for this translation
        createdAt:
          type: string
          description: ISO 8601 timestamp when translation was created
          example: '2024-10-18T12:33:09.099Z'
        updatedAt:
          type: string
          description: ISO 8601 timestamp when translation was last updated
          example: '2024-10-19T14:22:15.123Z'
    Article:
      type: object
      properties:
        object:
          type: string
          enum:
            - article
          description: Object type identifier
          example: article
        id:
          type: string
          description: Article unique identifier
          example: '1234567'
        title:
          type: string
          description: Article title
          example: Getting Started Guide
        description:
          type: string
          description: Article description
          example: Learn how to get started
        body:
          type: string
          description: Article body content (HTML)
          example: <p>Welcome to our guide.</p>
        slug:
          type: string
          description: URL slug
          example: 1234567-getting-started-guide
        icon:
          $ref: '#/components/schemas/ArticleIcon'
        parentId:
          type:
            - string
            - 'null'
          description: Parent collection ID
          example: '6474684'
        helpCenterId:
          type: string
          description: Help Center ID
          example: j7c5g8ah3ewxp4lo
        organization:
          type: string
          description: Organization ID
          example: 6595518396205e06b897ad65
        state:
          type: string
          enum:
            - live
            - draft
          description: Article state
          example: live
        defaultLocale:
          type: string
          enum:
            - bn
            - bs
            - pt-BR
            - bg
            - ca
            - hr
            - cs
            - da
            - nl
            - en
            - et
            - fi
            - fr
            - de
            - el
            - hi
            - hu
            - id
            - it
            - ja
            - ko
            - lv
            - lt
            - ms
            - mn
            - nb
            - pl
            - pt
            - ro
            - ru
            - sr
            - zh-CN
            - sk
            - sl
            - es
            - sw
            - sv
            - th
            - zh-TW
            - tr
            - uk
            - vi
          description: Default locale
          example: en
        locale:
          type: string
          enum:
            - bn
            - bs
            - pt-BR
            - bg
            - ca
            - hr
            - cs
            - da
            - nl
            - en
            - et
            - fi
            - fr
            - de
            - el
            - hi
            - hu
            - id
            - it
            - ja
            - ko
            - lv
            - lt
            - ms
            - mn
            - nb
            - pl
            - pt
            - ro
            - ru
            - sr
            - zh-CN
            - sk
            - sl
            - es
            - sw
            - sv
            - th
            - zh-TW
            - tr
            - uk
            - vi
          description: Current locale
          example: en
        availableLocales:
          type: array
          items:
            type: string
            enum:
              - bn
              - bs
              - pt-BR
              - bg
              - ca
              - hr
              - cs
              - da
              - nl
              - en
              - et
              - fi
              - fr
              - de
              - el
              - hi
              - hu
              - id
              - it
              - ja
              - ko
              - lv
              - lt
              - ms
              - mn
              - nb
              - pl
              - pt
              - ro
              - ru
              - sr
              - zh-CN
              - sk
              - sl
              - es
              - sw
              - sv
              - th
              - zh-TW
              - tr
              - uk
              - vi
            description: Locale code for localized content
            example: en
          description: Available locales
          example:
            - en
            - de
        publishedLocales:
          type: array
          items:
            type: string
            enum:
              - bn
              - bs
              - pt-BR
              - bg
              - ca
              - hr
              - cs
              - da
              - nl
              - en
              - et
              - fi
              - fr
              - de
              - el
              - hi
              - hu
              - id
              - it
              - ja
              - ko
              - lv
              - lt
              - ms
              - mn
              - nb
              - pl
              - pt
              - ro
              - ru
              - sr
              - zh-CN
              - sk
              - sl
              - es
              - sw
              - sv
              - th
              - zh-TW
              - tr
              - uk
              - vi
            description: Locale code for localized content
            example: en
          description: Published locales
          example:
            - en
        featurebaseUrl:
          type: string
          description: Featurebase URL
          example: >-
            https://yourorg.featurebase.app/en/help/articles/1234567-getting-started-guide
        externalUrl:
          type: string
          description: External URL
          example: >-
            https://help.yourdomain.com/en/articles/1234567-getting-started-guide
        author:
          $ref: '#/components/schemas/ArticleAuthor'
        order:
          type:
            - number
            - 'null'
          description: Display order
          example: 1
        isPublished:
          type: boolean
          description: Whether the article is published
          example: true
        isDraftDiffersFromLive:
          type: boolean
          description: Whether draft differs from live
          example: false
        translations:
          type: object
          properties:
            bn:
              $ref: '#/components/schemas/ArticleTranslation'
            bs:
              $ref: '#/components/schemas/ArticleTranslation'
            pt-BR:
              $ref: '#/components/schemas/ArticleTranslation'
            bg:
              $ref: '#/components/schemas/ArticleTranslation'
            ca:
              $ref: '#/components/schemas/ArticleTranslation'
            hr:
              $ref: '#/components/schemas/ArticleTranslation'
            cs:
              $ref: '#/components/schemas/ArticleTranslation'
            da:
              $ref: '#/components/schemas/ArticleTranslation'
            nl:
              $ref: '#/components/schemas/ArticleTranslation'
            en:
              $ref: '#/components/schemas/ArticleTranslation'
            et:
              $ref: '#/components/schemas/ArticleTranslation'
            fi:
              $ref: '#/components/schemas/ArticleTranslation'
            fr:
              $ref: '#/components/schemas/ArticleTranslation'
            de:
              $ref: '#/components/schemas/ArticleTranslation'
            el:
              $ref: '#/components/schemas/ArticleTranslation'
            hi:
              $ref: '#/components/schemas/ArticleTranslation'
            hu:
              $ref: '#/components/schemas/ArticleTranslation'
            id:
              $ref: '#/components/schemas/ArticleTranslation'
            it:
              $ref: '#/components/schemas/ArticleTranslation'
            ja:
              $ref: '#/components/schemas/ArticleTranslation'
            ko:
              $ref: '#/components/schemas/ArticleTranslation'
            lv:
              $ref: '#/components/schemas/ArticleTranslation'
            lt:
              $ref: '#/components/schemas/ArticleTranslation'
            ms:
              $ref: '#/components/schemas/ArticleTranslation'
            mn:
              $ref: '#/components/schemas/ArticleTranslation'
            nb:
              $ref: '#/components/schemas/ArticleTranslation'
            pl:
              $ref: '#/components/schemas/ArticleTranslation'
            pt:
              $ref: '#/components/schemas/ArticleTranslation'
            ro:
              $ref: '#/components/schemas/ArticleTranslation'
            ru:
              $ref: '#/components/schemas/ArticleTranslation'
            sr:
              $ref: '#/components/schemas/ArticleTranslation'
            zh-CN:
              $ref: '#/components/schemas/ArticleTranslation'
            sk:
              $ref: '#/components/schemas/ArticleTranslation'
            sl:
              $ref: '#/components/schemas/ArticleTranslation'
            es:
              $ref: '#/components/schemas/ArticleTranslation'
            sw:
              $ref: '#/components/schemas/ArticleTranslation'
            sv:
              $ref: '#/components/schemas/ArticleTranslation'
            th:
              $ref: '#/components/schemas/ArticleTranslation'
            zh-TW:
              $ref: '#/components/schemas/ArticleTranslation'
            tr:
              $ref: '#/components/schemas/ArticleTranslation'
            uk:
              $ref: '#/components/schemas/ArticleTranslation'
            vi:
              $ref: '#/components/schemas/ArticleTranslation'
          description: Translations by locale code
        createdAt:
          type: string
          description: ISO 8601 timestamp when created
          example: '2024-10-18T12:33:09.099Z'
        updatedAt:
          type: string
          description: ISO 8601 timestamp when last updated
          example: '2024-10-18T13:03:25.921Z'
        liveUpdatedAt:
          type: string
          description: ISO 8601 timestamp when live version was last updated
          example: '2024-10-18T13:03:25.921Z'
        path:
          type: string
          description: Path to article within help center hierarchy
          example: /getting-started
        surveyId:
          type: string
          description: Associated survey ID
          example: 6743752ca81ae59d25cf834b
        visibleBy:
          type: array
          items:
            type: string
          description: Visibility settings
          example:
            - everyone
        translationCreatedAt:
          type: string
          description: ISO 8601 timestamp when translation was created
          example: '2024-10-18T12:33:09.099Z'
        translationUpdatedAt:
          type: string
          description: ISO 8601 timestamp when translation was last updated
          example: '2024-10-19T14:22:15.123Z'
      required:
        - object
        - id
        - helpCenterId
        - organization
        - state
        - locale
        - availableLocales
        - createdAt
        - updatedAt
    ArticleList:
      type: object
      properties:
        object:
          type: string
          enum:
            - list
          description: Object type identifier
          example: list
        data:
          type: array
          items:
            $ref: '#/components/schemas/Article'
          description: Array of article objects
          example: []
        nextCursor:
          type:
            - string
            - 'null'
          description: Cursor for fetching the next page (cursor-based pagination)
          example: eyJpZCI6IjY3NDM3NTJjYTgxYWU1OWQyNWNmODM0YiJ9
      required:
        - object
        - data
        - nextCursor
    ArticleIconInput_Nova:
      type:
        - object
        - 'null'
      properties:
        value:
          type: string
          maxLength: 255
          description: Icon value
          example: 📖
        type:
          type: string
          enum:
            - emoji
            - predefined
          description: Type of icon (emoji or predefined only)
          example: emoji
      required:
        - value
        - type
      description: Icon object for the article
    ArticleTranslationInput_Nova:
      type: object
      properties:
        title:
          type: string
          maxLength: 512
          description: Article title in this locale
          example: Getting Started Guide
        description:
          type: string
          maxLength: 512
          description: Article description in this locale
          example: Learn how to get started
        body:
          type: string
          description: Article body content in this locale (HTML or markdown)
          example: <p>Welcome to our guide.</p>
    CreateArticleBody_Nova:
      type: object
      properties:
        title:
          type: string
          maxLength: 512
          description: The title of the article
          example: Getting Started Guide
        description:
          type: string
          maxLength: 512
          description: A brief description of the article
          example: Learn how to get started with our platform
        body:
          type: string
          description: >-
            The HTML content of the article (supports external image URLs and
            base64 data URIs)
          example: <p>Welcome to our getting started guide.</p>
        formatter:
          type: string
          enum:
            - default
            - ai
          default: default
          description: >-
            Content formatter - "ai" converts markdown/html to Featurebase
            format using AI
          example: default
        parentId:
          type: string
          minLength: 1
          maxLength: 16
          pattern: ^[a-zA-Z0-9]+$
          description: The ID of the parent collection
          example: '6474684'
        icon:
          $ref: '#/components/schemas/ArticleIconInput_Nova'
        state:
          type: string
          enum:
            - live
            - draft
          default: draft
          description: Article state - "live" publishes immediately, "draft" saves as draft
          example: draft
        translations:
          type: object
          properties:
            bn:
              $ref: '#/components/schemas/ArticleTranslationInput_Nova'
            bs:
              $ref: '#/components/schemas/ArticleTranslationInput_Nova'
            pt-BR:
              $ref: '#/components/schemas/ArticleTranslationInput_Nova'
            bg:
              $ref: '#/components/schemas/ArticleTranslationInput_Nova'
            ca:
              $ref: '#/components/schemas/ArticleTranslationInput_Nova'
            hr:
              $ref: '#/components/schemas/ArticleTranslationInput_Nova'
            cs:
              $ref: '#/components/schemas/ArticleTranslationInput_Nova'
            da:
              $ref: '#/components/schemas/ArticleTranslationInput_Nova'
            nl:
              $ref: '#/components/schemas/ArticleTranslationInput_Nova'
            en:
              $ref: '#/components/schemas/ArticleTranslationInput_Nova'
            et:
              $ref: '#/components/schemas/ArticleTranslationInput_Nova'
            fi:
              $ref: '#/components/schemas/ArticleTranslationInput_Nova'
            fr:
              $ref: '#/components/schemas/ArticleTranslationInput_Nova'
            de:
              $ref: '#/components/schemas/ArticleTranslationInput_Nova'
            el:
              $ref: '#/components/schemas/ArticleTranslationInput_Nova'
            hi:
              $ref: '#/components/schemas/ArticleTranslationInput_Nova'
            hu:
              $ref: '#/components/schemas/ArticleTranslationInput_Nova'
            id:
              $ref: '#/components/schemas/ArticleTranslationInput_Nova'
            it:
              $ref: '#/components/schemas/ArticleTranslationInput_Nova'
            ja:
              $ref: '#/components/schemas/ArticleTranslationInput_Nova'
            ko:
              $ref: '#/components/schemas/ArticleTranslationInput_Nova'
            lv:
              $ref: '#/components/schemas/ArticleTranslationInput_Nova'
            lt:
              $ref: '#/components/schemas/ArticleTranslationInput_Nova'
            ms:
              $ref: '#/components/schemas/ArticleTranslationInput_Nova'
            mn:
              $ref: '#/components/schemas/ArticleTranslationInput_Nova'
            nb:
              $ref: '#/components/schemas/ArticleTranslationInput_Nova'
            pl:
              $ref: '#/components/schemas/ArticleTranslationInput_Nova'
            pt:
              $ref: '#/components/schemas/ArticleTranslationInput_Nova'
            ro:
              $ref: '#/components/schemas/ArticleTranslationInput_Nova'
            ru:
              $ref: '#/components/schemas/ArticleTranslationInput_Nova'
            sr:
              $ref: '#/components/schemas/ArticleTranslationInput_Nova'
            zh-CN:
              $ref: '#/components/schemas/ArticleTranslationInput_Nova'
            sk:
              $ref: '#/components/schemas/ArticleTranslationInput_Nova'
            sl:
              $ref: '#/components/schemas/ArticleTranslationInput_Nova'
            es:
              $ref: '#/components/schemas/ArticleTranslationInput_Nova'
            sw:
              $ref: '#/components/schemas/ArticleTranslationInput_Nova'
            sv:
              $ref: '#/components/schemas/ArticleTranslationInput_Nova'
            th:
              $ref: '#/components/schemas/ArticleTranslationInput_Nova'
            zh-TW:
              $ref: '#/components/schemas/ArticleTranslationInput_Nova'
            tr:
              $ref: '#/components/schemas/ArticleTranslationInput_Nova'
            uk:
              $ref: '#/components/schemas/ArticleTranslationInput_Nova'
            vi:
              $ref: '#/components/schemas/ArticleTranslationInput_Nova'
          description: Dictionary of translations keyed by locale code
      required:
        - title
      additionalProperties: false
    UpdateArticleBody_Nova:
      type: object
      properties:
        title:
          type: string
          maxLength: 512
          description: The new title of the article
          example: Updated Getting Started Guide
        description:
          type: string
          maxLength: 512
          description: The new description of the article
          example: Updated description
        body:
          type: string
          description: The new HTML content of the article
          example: <p>Updated content.</p>
        formatter:
          type: string
          enum:
            - default
            - ai
          default: default
          description: Content formatter
          example: default
        icon:
          allOf:
            - $ref: '#/components/schemas/ArticleIconInput_Nova'
            - description: Updated icon object for the article
        parentId:
          type:
            - string
            - 'null'
          minLength: 1
          maxLength: 16
          pattern: ^[a-zA-Z0-9]+$
          description: New parent collection ID
          example: '6474684'
        authorId:
          type: string
          description: ID of the new author (must be a member of the organization)
          example: 507f1f77bcf86cd799439011
        state:
          type: string
          enum:
            - live
            - draft
          description: Article state - if "live", publishes immediately
          example: live
        translations:
          type: object
          properties:
            bn:
              $ref: '#/components/schemas/ArticleTranslationInput_Nova'
            bs:
              $ref: '#/components/schemas/ArticleTranslationInput_Nova'
            pt-BR:
              $ref: '#/components/schemas/ArticleTranslationInput_Nova'
            bg:
              $ref: '#/components/schemas/ArticleTranslationInput_Nova'
            ca:
              $ref: '#/components/schemas/ArticleTranslationInput_Nova'
            hr:
              $ref: '#/components/schemas/ArticleTranslationInput_Nova'
            cs:
              $ref: '#/components/schemas/ArticleTranslationInput_Nova'
            da:
              $ref: '#/components/schemas/ArticleTranslationInput_Nova'
            nl:
              $ref: '#/components/schemas/ArticleTranslationInput_Nova'
            en:
              $ref: '#/components/schemas/ArticleTranslationInput_Nova'
            et:
              $ref: '#/components/schemas/ArticleTranslationInput_Nova'
            fi:
              $ref: '#/components/schemas/ArticleTranslationInput_Nova'
            fr:
              $ref: '#/components/schemas/ArticleTranslationInput_Nova'
            de:
              $ref: '#/components/schemas/ArticleTranslationInput_Nova'
            el:
              $ref: '#/components/schemas/ArticleTranslationInput_Nova'
            hi:
              $ref: '#/components/schemas/ArticleTranslationInput_Nova'
            hu:
              $ref: '#/components/schemas/ArticleTranslationInput_Nova'
            id:
              $ref: '#/components/schemas/ArticleTranslationInput_Nova'
            it:
              $ref: '#/components/schemas/ArticleTranslationInput_Nova'
            ja:
              $ref: '#/components/schemas/ArticleTranslationInput_Nova'
            ko:
              $ref: '#/components/schemas/ArticleTranslationInput_Nova'
            lv:
              $ref: '#/components/schemas/ArticleTranslationInput_Nova'
            lt:
              $ref: '#/components/schemas/ArticleTranslationInput_Nova'
            ms:
              $ref: '#/components/schemas/ArticleTranslationInput_Nova'
            mn:
              $ref: '#/components/schemas/ArticleTranslationInput_Nova'
            nb:
              $ref: '#/components/schemas/ArticleTranslationInput_Nova'
            pl:
              $ref: '#/components/schemas/ArticleTranslationInput_Nova'
            pt:
              $ref: '#/components/schemas/ArticleTranslationInput_Nova'
            ro:
              $ref: '#/components/schemas/ArticleTranslationInput_Nova'
            ru:
              $ref: '#/components/schemas/ArticleTranslationInput_Nova'
            sr:
              $ref: '#/components/schemas/ArticleTranslationInput_Nova'
            zh-CN:
              $ref: '#/components/schemas/ArticleTranslationInput_Nova'
            sk:
              $ref: '#/components/schemas/ArticleTranslationInput_Nova'
            sl:
              $ref: '#/components/schemas/ArticleTranslationInput_Nova'
            es:
              $ref: '#/components/schemas/ArticleTranslationInput_Nova'
            sw:
              $ref: '#/components/schemas/ArticleTranslationInput_Nova'
            sv:
              $ref: '#/components/schemas/ArticleTranslationInput_Nova'
            th:
              $ref: '#/components/schemas/ArticleTranslationInput_Nova'
            zh-TW:
              $ref: '#/components/schemas/ArticleTranslationInput_Nova'
            tr:
              $ref: '#/components/schemas/ArticleTranslationInput_Nova'
            uk:
              $ref: '#/components/schemas/ArticleTranslationInput_Nova'
            vi:
              $ref: '#/components/schemas/ArticleTranslationInput_Nova'
          description: Dictionary of updated translations keyed by locale code
      additionalProperties: false
    DeletedArticle:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier of the deleted article
          example: '1234567'
        object:
          type: string
          enum:
            - article
          description: Object type identifier
          example: article
        deleted:
          type: boolean
          enum:
            - true
          description: Indicates the resource was deleted
          example: true
      required:
        - id
        - object
        - deleted
    ContactList:
      type: object
      properties:
        object:
          type: string
          enum:
            - list
          description: Object type identifier
          example: list
        data:
          type: array
          items:
            allOf:
              - $ref: '#/components/schemas/Contact'
              - type: object
          description: Array of contacts
          example: []
        nextCursor:
          type:
            - string
            - 'null'
          description: Cursor for fetching the next page (cursor-based pagination)
          example: eyJpZCI6IjUwN2YxZjc3YmNmODZjZDc5OTQzOTAxMSJ9
      required:
        - object
        - data
        - nextCursor
    UpsertContactCompany:
      type: object
      properties:
        id:
          type: string
          minLength: 1
          maxLength: 500
          description: External company ID from your system
          example: company_123
        name:
          type: string
          minLength: 1
          maxLength: 500
          description: Company name
          example: Acme Inc
        createdAt:
          type:
            - string
            - 'null'
          description: When the company was created (ISO 8601)
          example: '2024-01-15T10:30:00Z'
        monthlySpend:
          type: number
          minimum: 0
          description: Monthly spend/revenue from this company
          example: 500
        customFields:
          type: object
          description: >-
            Custom field values on the company. Values can be string, number,
            boolean, null, or array of primitives.
          properties:
            plan:
              type: string
              example: enterprise
            industry:
              type: string
              example: Technology
            priority:
              type: string
              example: high
        companyHash:
          type: string
          maxLength: 256
          description: HMAC-SHA256 hash of company ID for identity verification
          example: a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6
        companySize:
          type:
            - number
            - 'null'
          minimum: 0
          description: Number of employees in the company
          example: 50
        industry:
          type: string
          maxLength: 500
          description: Industry the company operates in
          example: Technology
        website:
          type: string
          maxLength: 500
          description: Company website URL
          example: https://acme.com
        plan:
          type: string
          maxLength: 500
          description: Current plan/subscription name
          example: enterprise
      required:
        - id
        - name
      additionalProperties: false
    UpsertContactBody:
      type: object
      properties:
        email:
          type: string
          maxLength: 500
          format: email
          description: >-
            Contact email address. Used for identification if userId is not
            provided.
          example: john@example.com
        name:
          type: string
          maxLength: 500
          description: Contact display name
          example: John Doe
        userId:
          type: string
          maxLength: 500
          description: >-
            External user ID from your system. Takes precedence over email for
            identification.
          example: usr_12345
        userHash:
          type: string
          maxLength: 256
          description: HMAC-SHA256 hash of userId or email for identity verification
          example: a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6
        profilePicture:
          type:
            - string
            - 'null'
          format: uri
          description: Profile picture URL
          example: https://example.com/avatar.png
        companies:
          type: array
          items:
            $ref: '#/components/schemas/UpsertContactCompany'
          maxItems: 100
          description: Companies the contact belongs to
        createdAt:
          type:
            - string
            - 'null'
          description: When the contact was created in your system (ISO 8601)
          example: '2024-01-15T10:30:00Z'
        customFields:
          type: object
          description: >-
            Custom field values on the contact. Values can be string, number,
            boolean, null, or array of primitives.
          properties:
            plan:
              type: string
              example: pro
            signupSource:
              type: string
              example: website
            accountType:
              type: string
              example: premium
        subscribedToChangelog:
          type: boolean
          description: Whether the contact is subscribed to changelog updates
          example: true
        locale:
          type: string
          maxLength: 10
          description: Contact locale/language preference
          example: en
        phone:
          type:
            - string
            - 'null'
          maxLength: 500
          description: Contact phone number
          example: '+1234567890'
        roles:
          type: array
          items:
            type: string
            maxLength: 255
          maxItems: 100
          description: Array of role IDs to assign to the contact
          example:
            - role_vip
            - role_beta
      additionalProperties: false
    DeletedContact:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier of the deleted contact
          example: 507f1f77bcf86cd799439011
        object:
          type: string
          enum:
            - contact
          description: Object type identifier
          example: contact
        deleted:
          type: boolean
          enum:
            - true
          description: Indicates the resource was deleted
          example: true
      required:
        - id
        - object
        - deleted
    BlockedContact:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier of the blocked contact
          example: 507f1f77bcf86cd799439011
        object:
          type: string
          enum:
            - contact
          description: Object type identifier
          example: contact
        blocked:
          type: boolean
          enum:
            - true
          description: Indicates the contact was blocked
          example: true
      required:
        - id
        - object
        - blocked
    UnblockedContact:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier of the unblocked contact
          example: 507f1f77bcf86cd799439011
        object:
          type: string
          enum:
            - contact
          description: Object type identifier
          example: contact
        unblocked:
          type: boolean
          enum:
            - true
          description: Indicates the contact was unblocked
          example: true
      required:
        - id
        - object
        - unblocked
    Icon:
      type:
        - object
        - 'null'
      properties:
        value:
          type: string
          description: Icon value
          example: 👥
        type:
          type: string
          enum:
            - emoji
            - predefined
            - external
          description: Type of icon
          example: emoji
      required:
        - value
        - type
      description: Team icon
    Team:
      type: object
      properties:
        object:
          type: string
          enum:
            - team
          description: Object type identifier
          example: team
        id:
          type: string
          description: Unique identifier
          example: 507f1f77bcf86cd799439011
        name:
          type: string
          description: Team name
          example: Support Team
        color:
          type: string
          description: Team color in hex format
          example: '#3B82F6'
        icon:
          $ref: '#/components/schemas/Icon'
        members:
          type: array
          items:
            type: string
          description: Array of admin IDs who are members of this team
          example:
            - 5fef50c5e9458a0012f82456
            - 5fef50c5e9458a0012f82457
      required:
        - object
        - id
        - name
        - color
        - icon
        - members
    TeamList:
      type: object
      properties:
        object:
          type: string
          enum:
            - list
          description: Object type identifier
          example: list
        data:
          type: array
          items:
            $ref: '#/components/schemas/Team'
          description: Array of teams
          example: []
      required:
        - object
        - data
    CompanyList:
      type: object
      properties:
        object:
          type: string
          enum:
            - list
          description: Object type identifier
          example: list
        data:
          type: array
          items:
            $ref: '#/components/schemas/Company'
          description: Array of companies
          example: []
        nextCursor:
          type:
            - string
            - 'null'
          maxLength: 512
          description: Cursor for fetching the next page (cursor-based pagination)
          example: eyJpZCI6IjUwN2YxZjc3YmNmODZjZDc5OTQzOTAxMSJ9
      required:
        - object
        - data
        - nextCursor
    UpsertCompanyBody:
      type: object
      properties:
        companyId:
          type: string
          minLength: 1
          maxLength: 500
          description: >-
            External company ID from your system. Used as the unique identifier
            for upsert matching.
          example: comp_12345
        name:
          type: string
          minLength: 1
          maxLength: 500
          description: Company name
          example: Acme Inc
        monthlySpend:
          type: number
          minimum: 0
          description: Monthly spend/revenue from this company
          example: 5000
        industry:
          type: string
          maxLength: 500
          description: Industry the company operates in
          example: Technology
        website:
          type: string
          maxLength: 500
          description: Company website URL
          example: https://acme.com
        plan:
          type: string
          maxLength: 500
          description: Current plan/subscription name
          example: enterprise
        companySize:
          type:
            - number
            - 'null'
          minimum: 0
          description: Number of employees in the company
          example: 250
        createdAt:
          type:
            - string
            - 'null'
          description: When the company was created in your system (ISO 8601)
          example: '2024-01-15T10:30:00Z'
        customFields:
          type: object
          description: >-
            Custom field values on the company. Values can be string, number,
            boolean, null, or array of primitives.
          properties:
            region:
              type: string
              example: EMEA
            tier:
              type: string
              example: gold
            priority:
              type: string
              example: high
      required:
        - companyId
        - name
      additionalProperties: false
    DeletedCompany:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier of the deleted company
          example: 507f1f77bcf86cd799439011
        object:
          type: string
          enum:
            - company
          description: Object type identifier
          example: company
        deleted:
          type: boolean
          enum:
            - true
          description: Indicates the resource was deleted
          example: true
      required:
        - id
        - object
        - deleted
    AttachContactToCompanyBody:
      type: object
      properties:
        contactId:
          type: string
          description: >-
            The Featurebase internal ID of the contact to attach (MongoDB
            ObjectId)
          example: 507f1f77bcf86cd799439012
      required:
        - contactId
    ConversationParticipant:
      type: object
      properties:
        type:
          type: string
          enum:
            - customer
            - lead
            - admin
            - bot
            - guest
            - integration
          description: Type of participant
          example: customer
        id:
          type: string
          description: Participant ID
          example: 676f0f6765bdaa7d7d760f88
      required:
        - type
        - id
    MessageSource:
      type: object
      properties:
        channel:
          type: string
          enum:
            - unknown
            - desktop
            - android
            - ios
            - email
          description: Channel through which the conversation was initiated
          example: desktop
        deliveredAs:
          type: string
          enum:
            - customer_initiated
            - admin_initiated
          description: How the conversation was initiated
          example: customer_initiated
        subject:
          type: string
          description: Subject line for email conversations
          example: Question about pricing
        bodyHtml:
          type: string
          description: Body of the initial message as HTML with signed image URLs
          example: <p>Hi, I have a question about your enterprise plan...</p>
        bodyMarkdown:
          type: string
          description: Body of the initial message as markdown
          example: Hi, I have a question about your enterprise plan...
        author:
          $ref: '#/components/schemas/ConversationParticipant'
        url:
          type: string
          description: URL where the conversation was initiated
          example: https://example.com/pricing
      required:
        - channel
        - bodyHtml
        - bodyMarkdown
    ReadReceipt:
      type: object
      properties:
        id:
          type: string
          description: The internal ID of the user
          example: 507f1f77bcf86cd799439011
        userType:
          type: string
          enum:
            - admin
            - customer
            - lead
          description: Type of user who has read the conversation
          example: admin
        lastReadPartId:
          type: string
          description: >-
            The ID of the last conversation part this user has read. Note: This
            reflects the system-tracked read position and may reference a part
            the user cannot directly access (e.g., internal notes for contacts).
            The read state is advanced to the latest part in the conversation
            regardless of part visibility.
          example: '8'
      required:
        - id
        - userType
        - lastReadPartId
    ConversationPartAuthor:
      type:
        - object
        - 'null'
      properties:
        type:
          type: string
          enum:
            - customer
            - lead
            - admin
            - bot
            - guest
            - integration
          description: Type of author
          example: customer
        id:
          type:
            - string
            - 'null'
          description: Author ID
          example: 676f0f6765bdaa7d7d760f88
        name:
          type: string
          description: Author display name
          example: John Doe
        email:
          type: string
          description: Author email address
          example: john@example.com
        profilePicture:
          type:
            - string
            - 'null'
          description: Author profile picture URL
          example: https://cdn.example.com/avatars/user.png
      required:
        - type
        - id
    UserMessagePart:
      type: object
      properties:
        object:
          type: string
          enum:
            - conversation_part
          description: Object type identifier
          example: conversation_part
        id:
          type: string
          description: Unique part identifier
          example: '1'
        createdAt:
          type: string
          description: ISO timestamp when the part was created
          example: '2025-01-15T10:30:00.000Z'
        updatedAt:
          type: string
          description: ISO timestamp when the part was last updated
          example: '2025-01-15T10:30:00.000Z'
        author:
          $ref: '#/components/schemas/ConversationPartAuthor'
        redacted:
          type: boolean
          description: Whether this message has been redacted
          example: false
        partType:
          type: string
          enum:
            - user_msg
          description: User message type
          example: user_msg
        bodyHtml:
          type:
            - string
            - 'null'
          description: Message body content as HTML with signed image URLs
          example: <p>Hello, I have a question about your product.</p>
        bodyMarkdown:
          type:
            - string
            - 'null'
          description: Message body content as markdown
          example: Hello, I have a question about your product.
        channel:
          type: string
          enum:
            - unknown
            - desktop
            - android
            - ios
            - email
          description: Channel through which the message was sent
          example: desktop
      required:
        - object
        - id
        - createdAt
        - updatedAt
        - partType
        - bodyHtml
        - bodyMarkdown
        - channel
      description: Message from a customer or lead
      title: User Message
    AdminMessagePart:
      type: object
      properties:
        object:
          type: string
          enum:
            - conversation_part
          description: Object type identifier
          example: conversation_part
        id:
          type: string
          description: Unique part identifier
          example: '1'
        createdAt:
          type: string
          description: ISO timestamp when the part was created
          example: '2025-01-15T10:30:00.000Z'
        updatedAt:
          type: string
          description: ISO timestamp when the part was last updated
          example: '2025-01-15T10:30:00.000Z'
        author:
          $ref: '#/components/schemas/ConversationPartAuthor'
        redacted:
          type: boolean
          description: Whether this message has been redacted
          example: false
        partType:
          type: string
          enum:
            - admin_msg
          description: Admin message type
          example: admin_msg
        bodyHtml:
          type:
            - string
            - 'null'
          description: Message body content as HTML with signed image URLs
          example: <p>Thanks for reaching out! I can help you with that.</p>
        bodyMarkdown:
          type:
            - string
            - 'null'
          description: Message body content as markdown
          example: Thanks for reaching out! I can help you with that.
        channel:
          type: string
          enum:
            - unknown
            - desktop
            - android
            - ios
            - email
          description: Channel through which the message was sent
          example: desktop
      required:
        - object
        - id
        - createdAt
        - updatedAt
        - partType
        - bodyHtml
        - bodyMarkdown
        - channel
      description: Message from an admin or support agent
      title: Admin Message
    AdminNotePart:
      type: object
      properties:
        object:
          type: string
          enum:
            - conversation_part
          description: Object type identifier
          example: conversation_part
        id:
          type: string
          description: Unique part identifier
          example: '1'
        createdAt:
          type: string
          description: ISO timestamp when the part was created
          example: '2025-01-15T10:30:00.000Z'
        updatedAt:
          type: string
          description: ISO timestamp when the part was last updated
          example: '2025-01-15T10:30:00.000Z'
        author:
          $ref: '#/components/schemas/ConversationPartAuthor'
        redacted:
          type: boolean
          description: Whether this message has been redacted
          example: false
        partType:
          type: string
          enum:
            - admin_note
          description: Admin internal note type
          example: admin_note
        bodyHtml:
          type:
            - string
            - 'null'
          description: Note body content as HTML with signed image URLs
          example: <p>Customer seems frustrated, escalating to tier 2.</p>
        bodyMarkdown:
          type:
            - string
            - 'null'
          description: Note body content as markdown
          example: Customer seems frustrated, escalating to tier 2.
      required:
        - object
        - id
        - createdAt
        - updatedAt
        - partType
        - bodyHtml
        - bodyMarkdown
      description: Internal note visible only to admins
      title: Admin Note
    EmailMessagePart:
      type: object
      properties:
        object:
          type: string
          enum:
            - conversation_part
          description: Object type identifier
          example: conversation_part
        id:
          type: string
          description: Unique part identifier
          example: '1'
        createdAt:
          type: string
          description: ISO timestamp when the part was created
          example: '2025-01-15T10:30:00.000Z'
        updatedAt:
          type: string
          description: ISO timestamp when the part was last updated
          example: '2025-01-15T10:30:00.000Z'
        author:
          $ref: '#/components/schemas/ConversationPartAuthor'
        redacted:
          type: boolean
          description: Whether this message has been redacted
          example: false
        partType:
          type: string
          enum:
            - email_msg
          description: Email message type
          example: email_msg
        bodyHtml:
          type:
            - string
            - 'null'
          description: Email body content as HTML with signed image URLs
          example: <p>Thank you for your email...</p>
        bodyMarkdown:
          type:
            - string
            - 'null'
          description: Email body content as markdown
          example: Thank you for your email...
        channel:
          type: string
          enum:
            - email
          description: Email channel
          example: email
      required:
        - object
        - id
        - createdAt
        - updatedAt
        - partType
        - bodyHtml
        - bodyMarkdown
        - channel
      description: Message sent via email
      title: Email Message
    BotMessagePart:
      type: object
      properties:
        object:
          type: string
          enum:
            - conversation_part
          description: Object type identifier
          example: conversation_part
        id:
          type: string
          description: Unique part identifier
          example: '1'
        createdAt:
          type: string
          description: ISO timestamp when the part was created
          example: '2025-01-15T10:30:00.000Z'
        updatedAt:
          type: string
          description: ISO timestamp when the part was last updated
          example: '2025-01-15T10:30:00.000Z'
        author:
          $ref: '#/components/schemas/ConversationPartAuthor'
        redacted:
          type: boolean
          description: Whether this message has been redacted
          example: false
        partType:
          type: string
          enum:
            - bot_msg
          description: Bot message type
          example: bot_msg
        bodyHtml:
          type:
            - string
            - 'null'
          description: Bot message body content as HTML with signed image URLs
          example: <p>Based on your question, here is what I found...</p>
        bodyMarkdown:
          type:
            - string
            - 'null'
          description: Bot message body content as markdown
          example: Based on your question, here is what I found...
        channel:
          type: string
          enum:
            - unknown
            - desktop
            - android
            - ios
            - email
          description: Channel through which the message was sent
          example: desktop
      required:
        - object
        - id
        - createdAt
        - updatedAt
        - partType
        - bodyHtml
        - bodyMarkdown
      description: Automated message from AI or bot
      title: Bot Message
    QuickReplyOptionsPart:
      type: object
      properties:
        object:
          type: string
          enum:
            - conversation_part
          description: Object type identifier
          example: conversation_part
        id:
          type: string
          description: Unique part identifier
          example: '1'
        createdAt:
          type: string
          description: ISO timestamp when the part was created
          example: '2025-01-15T10:30:00.000Z'
        updatedAt:
          type: string
          description: ISO timestamp when the part was last updated
          example: '2025-01-15T10:30:00.000Z'
        author:
          $ref: '#/components/schemas/ConversationPartAuthor'
        redacted:
          type: boolean
          description: Whether this message has been redacted
          example: false
        partType:
          type: string
          enum:
            - quick_reply_opts
          description: Quick reply options type
          example: quick_reply_opts
        replyOptions:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
                description: Option ID
                example: opt_1
              text:
                type: string
                description: Option text
                example: Yes, that helps!
            required:
              - id
              - text
          description: Available reply options
          example:
            - id: opt_1
              text: Yes, that helps!
      required:
        - object
        - id
        - createdAt
        - updatedAt
        - partType
        - replyOptions
      description: Presents options for user to choose from
      title: Quick Reply Options
    QuickReplyResponsePart:
      type: object
      properties:
        object:
          type: string
          enum:
            - conversation_part
          description: Object type identifier
          example: conversation_part
        id:
          type: string
          description: Unique part identifier
          example: '1'
        createdAt:
          type: string
          description: ISO timestamp when the part was created
          example: '2025-01-15T10:30:00.000Z'
        updatedAt:
          type: string
          description: ISO timestamp when the part was last updated
          example: '2025-01-15T10:30:00.000Z'
        author:
          $ref: '#/components/schemas/ConversationPartAuthor'
        redacted:
          type: boolean
          description: Whether this message has been redacted
          example: false
        partType:
          type: string
          enum:
            - quick_reply_resp
          description: Quick reply response type
          example: quick_reply_resp
        bodyHtml:
          type: string
          description: The selected option text as HTML
          example: Yes, that helps!
        bodyMarkdown:
          type: string
          description: The selected option text as markdown
          example: Yes, that helps!
        selectedOptionId:
          type: string
          description: ID of the selected option
          example: opt_1
      required:
        - object
        - id
        - createdAt
        - updatedAt
        - partType
        - bodyHtml
        - bodyMarkdown
        - selectedOptionId
      description: User's selection from quick reply options
      title: Quick Reply Response
    AttributeCollectionPromptPart:
      type: object
      properties:
        object:
          type: string
          enum:
            - conversation_part
          description: Object type identifier
          example: conversation_part
        id:
          type: string
          description: Unique part identifier
          example: '1'
        createdAt:
          type: string
          description: ISO timestamp when the part was created
          example: '2025-01-15T10:30:00.000Z'
        updatedAt:
          type: string
          description: ISO timestamp when the part was last updated
          example: '2025-01-15T10:30:00.000Z'
        author:
          $ref: '#/components/schemas/ConversationPartAuthor'
        redacted:
          type: boolean
          description: Whether this message has been redacted
          example: false
        partType:
          type: string
          enum:
            - attr_prompt
          description: Attribute collection prompt type
          example: attr_prompt
        form:
          type: object
          properties:
            id:
              type: string
              description: Form ID
              example: form_123
            attributes:
              type: array
              items:
                type: object
                properties:
                  identifier:
                    type: string
                    description: Field identifier
                    example: email
                  name:
                    type: string
                    description: Field display name
                    example: Email Address
                  type:
                    type: string
                    description: Field type
                    example: text
                required:
                  - identifier
                  - name
                  - type
              description: Form fields
              example:
                - identifier: email
                  name: Email Address
                  type: text
          required:
            - id
            - attributes
          description: Form configuration
      required:
        - object
        - id
        - createdAt
        - updatedAt
        - partType
        - form
      description: Requests information from user via form
      title: Attribute Collection Prompt
    AttributeCollectionCompletePart:
      type: object
      properties:
        object:
          type: string
          enum:
            - conversation_part
          description: Object type identifier
          example: conversation_part
        id:
          type: string
          description: Unique part identifier
          example: '1'
        createdAt:
          type: string
          description: ISO timestamp when the part was created
          example: '2025-01-15T10:30:00.000Z'
        updatedAt:
          type: string
          description: ISO timestamp when the part was last updated
          example: '2025-01-15T10:30:00.000Z'
        partType:
          type: string
          enum:
            - attr_complete
          description: Attribute collection complete type
          example: attr_complete
      required:
        - object
        - id
        - createdAt
        - updatedAt
        - partType
      description: Indicates form was completed
      title: Attribute Collection Complete
    AssignmentPart:
      type: object
      properties:
        object:
          type: string
          enum:
            - conversation_part
          description: Object type identifier
          example: conversation_part
        id:
          type: string
          description: Unique part identifier
          example: '1'
        createdAt:
          type: string
          description: ISO timestamp when the part was created
          example: '2025-01-15T10:30:00.000Z'
        updatedAt:
          type: string
          description: ISO timestamp when the part was last updated
          example: '2025-01-15T10:30:00.000Z'
        partType:
          type: string
          enum:
            - assign
          description: Assignment type
          example: assign
        adminAssigneeId:
          type:
            - string
            - 'null'
          description: ID of the admin assigned to the conversation
          example: 507f1f77bcf86cd799439011
        adminAssignerId:
          type:
            - string
            - 'null'
          description: ID of the admin who made the assignment
          example: 507f1f77bcf86cd799439012
        teamAssigneeId:
          type:
            - string
            - 'null'
          description: ID of the team assigned to the conversation
          example: 507f1f77bcf86cd799439013
      required:
        - object
        - id
        - createdAt
        - updatedAt
        - partType
      description: Conversation assigned to admin or team
      title: Assignment
    StatusChangePart:
      type: object
      properties:
        object:
          type: string
          enum:
            - conversation_part
          description: Object type identifier
          example: conversation_part
        id:
          type: string
          description: Unique part identifier
          example: '1'
        createdAt:
          type: string
          description: ISO timestamp when the part was created
          example: '2025-01-15T10:30:00.000Z'
        updatedAt:
          type: string
          description: ISO timestamp when the part was last updated
          example: '2025-01-15T10:30:00.000Z'
        partType:
          type: string
          enum:
            - status
          description: Status change type
          example: status
        status:
          type: string
          enum:
            - open
            - closed
            - snoozed
          description: New conversation status
          example: open
        snoozedUntil:
          type:
            - string
            - 'null'
          description: ISO timestamp until conversation is snoozed (if snoozed)
          example: '2025-01-16T09:00:00.000Z'
      required:
        - object
        - id
        - createdAt
        - updatedAt
        - partType
        - status
      description: Conversation state changed (open/closed/snoozed)
      title: Status Change
    PriorityChangePart:
      type: object
      properties:
        object:
          type: string
          enum:
            - conversation_part
          description: Object type identifier
          example: conversation_part
        id:
          type: string
          description: Unique part identifier
          example: '1'
        createdAt:
          type: string
          description: ISO timestamp when the part was created
          example: '2025-01-15T10:30:00.000Z'
        updatedAt:
          type: string
          description: ISO timestamp when the part was last updated
          example: '2025-01-15T10:30:00.000Z'
        partType:
          type: string
          enum:
            - priority
          description: Priority change type
          example: priority
        isPriority:
          type: boolean
          description: Whether the conversation is now marked as priority
          example: true
      required:
        - object
        - id
        - createdAt
        - updatedAt
        - partType
        - isPriority
      description: Conversation priority was updated
      title: Priority Change
    ParticipantAddedPart:
      type: object
      properties:
        object:
          type: string
          enum:
            - conversation_part
          description: Object type identifier
          example: conversation_part
        id:
          type: string
          description: Unique part identifier
          example: '1'
        createdAt:
          type: string
          description: ISO timestamp when the part was created
          example: '2025-01-15T10:30:00.000Z'
        updatedAt:
          type: string
          description: ISO timestamp when the part was last updated
          example: '2025-01-15T10:30:00.000Z'
        partType:
          type: string
          enum:
            - part_add
          description: Participant added type
          example: part_add
        participant:
          type: object
          properties:
            id:
              type: string
              description: Participant ID
              example: 676f0f6765bdaa7d7d760f88
            type:
              type: string
              enum:
                - customer
                - lead
                - admin
              description: Participant type
              example: customer
          required:
            - id
            - type
          description: The added participant
      required:
        - object
        - id
        - createdAt
        - updatedAt
        - partType
        - participant
      description: New participant joined the conversation
      title: Participant Added
    ConversationPart:
      oneOf:
        - $ref: '#/components/schemas/UserMessagePart'
        - $ref: '#/components/schemas/AdminMessagePart'
        - $ref: '#/components/schemas/AdminNotePart'
        - $ref: '#/components/schemas/EmailMessagePart'
        - $ref: '#/components/schemas/BotMessagePart'
        - $ref: '#/components/schemas/QuickReplyOptionsPart'
        - $ref: '#/components/schemas/QuickReplyResponsePart'
        - $ref: '#/components/schemas/AttributeCollectionPromptPart'
        - $ref: '#/components/schemas/AttributeCollectionCompletePart'
        - $ref: '#/components/schemas/AssignmentPart'
        - $ref: '#/components/schemas/StatusChangePart'
        - $ref: '#/components/schemas/PriorityChangePart'
        - $ref: '#/components/schemas/ParticipantAddedPart'
      discriminator:
        propertyName: partType
        mapping:
          user_msg: '#/components/schemas/UserMessagePart'
          admin_msg: '#/components/schemas/AdminMessagePart'
          admin_note: '#/components/schemas/AdminNotePart'
          email_msg: '#/components/schemas/EmailMessagePart'
          bot_msg: '#/components/schemas/BotMessagePart'
          quick_reply_opts: '#/components/schemas/QuickReplyOptionsPart'
          quick_reply_resp: '#/components/schemas/QuickReplyResponsePart'
          attr_prompt: '#/components/schemas/AttributeCollectionPromptPart'
          attr_complete: '#/components/schemas/AttributeCollectionCompletePart'
          assign: '#/components/schemas/AssignmentPart'
          status: '#/components/schemas/StatusChangePart'
          priority: '#/components/schemas/PriorityChangePart'
          part_add: '#/components/schemas/ParticipantAddedPart'
    Conversation:
      type: object
      properties:
        object:
          type: string
          enum:
            - conversation
          description: Object type identifier
          example: conversation
        id:
          type: string
          description: Unique conversation identifier
          example: '12345'
        title:
          type: string
          description: Conversation title
          example: Question about pricing
        state:
          type: string
          enum:
            - open
            - closed
            - snoozed
          description: Current state of the conversation
          example: open
        isBlocked:
          type: boolean
          description: Whether the user is blocked
          example: false
        priority:
          type: boolean
          description: Whether this conversation is marked as priority
          example: false
        prioritySetAt:
          type:
            - string
            - 'null'
          description: ISO timestamp when priority was set
          example: '2025-01-15T10:30:00.000Z'
        adminAssigneeId:
          type:
            - string
            - 'null'
          description: ID of the assigned admin
          example: 507f1f77bcf86cd799439011
        teamAssigneeId:
          type:
            - string
            - 'null'
          description: ID of the assigned team
          example: 507f1f77bcf86cd799439012
        userPreferredLanguage:
          type: string
          description: User's preferred language
          example: en
        source:
          $ref: '#/components/schemas/MessageSource'
        participants:
          type: array
          items:
            $ref: '#/components/schemas/ConversationParticipant'
          description: Participants in this conversation
        botConversationState:
          type: string
          enum:
            - active
            - handed_off_to_human
            - resolved
          description: State of AI agent handling for this conversation
          example: active
        botConversationStateLastUpdatedAt:
          type:
            - string
            - 'null'
          description: ISO timestamp when bot state last changed
          example: '2025-01-15T10:30:00.000Z'
        disableCustomerReply:
          type: boolean
          description: Whether customer replies are disabled
          example: false
        awaitingCustomerReply:
          type: boolean
          description: Whether we are awaiting a customer reply
          example: true
        lastActivityAt:
          type:
            - string
            - 'null'
          description: ISO timestamp of last activity
          example: '2025-01-15T12:30:00.000Z'
        waitingSince:
          type:
            - string
            - 'null'
          description: ISO timestamp when conversation started waiting
          example: '2025-01-15T10:30:00.000Z'
        snoozedUntil:
          type:
            - string
            - 'null'
          description: ISO timestamp until which conversation is snoozed
          example: '2025-01-16T09:00:00.000Z'
        createdAt:
          type: string
          description: ISO timestamp when conversation was created
          example: '2025-01-15T10:30:00.000Z'
        updatedAt:
          type: string
          description: ISO timestamp when conversation was last updated
          example: '2025-01-15T12:30:00.000Z'
        readReceipts:
          type: array
          items:
            $ref: '#/components/schemas/ReadReceipt'
          description: >-
            Read receipts indicating how far each participant has read in the
            conversation. Each receipt maps a user to their last-read
            conversation part. The tracked position reflects the system read
            state and may reference parts the user cannot directly view (e.g., a
            contact's read position may point to an internal admin note). Use
            these receipts to render read indicators and typing awareness, not
            to infer content access.
        conversationParts:
          type: array
          items:
            $ref: '#/components/schemas/ConversationPart'
          description: >-
            Array of conversation parts (messages). Only included when fetching
            a single conversation by ID.
      required:
        - object
        - id
        - state
        - isBlocked
        - priority
        - prioritySetAt
        - adminAssigneeId
        - teamAssigneeId
        - userPreferredLanguage
        - participants
        - botConversationStateLastUpdatedAt
        - lastActivityAt
        - waitingSince
        - snoozedUntil
        - createdAt
        - updatedAt
    ConversationList:
      type: object
      properties:
        object:
          type: string
          enum:
            - list
          description: Object type identifier
          example: list
        data:
          type: array
          items:
            $ref: '#/components/schemas/Conversation'
          description: Array of conversations
        nextCursor:
          type:
            - string
            - 'null'
          description: Cursor for fetching the next page
          example: eyJpZCI6IjEyMzQ1In0=
      required:
        - object
        - data
        - nextCursor
    ConversationFromContact:
      type: object
      properties:
        type:
          type: string
          enum:
            - contact
          description: >-
            The type of author. Use "contact" for customer/lead initiated
            conversations.
          example: contact
        id:
          type: string
          description: The Featurebase contact ID
          example: 676f0f6765bdaa7d7d760f88
      required:
        - type
        - id
      description: Conversation initiated by a contact
      title: Contact From
    ConversationFromAdmin:
      type: object
      properties:
        type:
          type: string
          enum:
            - admin
          description: >-
            The type of author. Use "admin" for admin initiated outreach
            conversations.
          example: admin
        id:
          type: string
          description: The Featurebase admin ID
          example: 507f1f77bcf86cd799439011
      required:
        - type
        - id
      description: Conversation initiated by an admin (outreach)
      title: Admin From
    ConversationFrom:
      anyOf:
        - $ref: '#/components/schemas/ConversationFromContact'
        - $ref: '#/components/schemas/ConversationFromAdmin'
      description: >-
        The author initiating the conversation. Use type "contact" for
        customer/lead or "admin" for outreach.
      discriminator:
        propertyName: type
        mapping:
          contact: '#/components/schemas/ConversationFromContact'
          admin: '#/components/schemas/ConversationFromAdmin'
    EmailRecipients:
      type: object
      properties:
        emails:
          type: array
          items:
            type: string
            format: email
          maxItems: 50
          description: Array of email addresses
          example:
            - john@example.com
        ids:
          type: array
          items:
            type: string
          maxItems: 50
          description: Array of Featurebase contact IDs
          example:
            - 676f0f6765bdaa7d7d760f88
      description: Primary recipients (To field)
    OutreachRecipients:
      type: object
      properties:
        to:
          $ref: '#/components/schemas/EmailRecipients'
        cc:
          allOf:
            - $ref: '#/components/schemas/EmailRecipients'
            - description: Carbon copy recipients (CC field)
        bcc:
          allOf:
            - $ref: '#/components/schemas/EmailRecipients'
            - description: Blind carbon copy recipients (BCC field)
      required:
        - to
      description: >-
        Recipients for admin-initiated outreach. Required when from.type is
        "admin". Specify at least one recipient in the "to" field.
    CreateConversationBody:
      type: object
      properties:
        from:
          $ref: '#/components/schemas/ConversationFrom'
        bodyMarkdown:
          type: string
          minLength: 1
          description: >-
            The content of the initial message in markdown format. Images
            referenced by URL or as base64 data URIs will be automatically
            uploaded and stored.
          example: |-
            Hello, I have a question about your product.

            ![screenshot](https://example.com/image.png)
        channel:
          type: string
          enum:
            - desktop
            - email
          default: desktop
          description: >-
            The channel for the conversation. Defaults to "desktop"
            (SDK/widget).
          example: desktop
        recipients:
          $ref: '#/components/schemas/OutreachRecipients'
        subject:
          type: string
          maxLength: 500
          description: >-
            Subject line for the email. Required when channel is "email" and
            from.type is "admin".
          example: Following up on your inquiry
        createdAt:
          type:
            - string
            - 'null'
          description: >-
            The time the conversation was created as an ISO timestamp. If not
            provided, the current time will be used. This field is recommended
            for migrating past conversations from another source.
          example: '2025-01-15T10:30:00.000Z'
      required:
        - from
        - bodyMarkdown
    DeletedConversation:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier of the deleted conversation
          example: '12345'
        object:
          type: string
          enum:
            - conversation
          description: Object type identifier
          example: conversation
        deleted:
          type: boolean
          enum:
            - true
          description: Indicates the resource was deleted
          example: true
      required:
        - id
        - object
        - deleted
    ContactReplyBody:
      type: object
      properties:
        type:
          type: string
          enum:
            - contact
          description: The type of author. Use "contact" for customer/lead replies.
          example: contact
        userId:
          type: string
          maxLength: 255
          description: The external user ID from your system
          example: user_123
        id:
          type: string
          description: The Featurebase contact ID
          example: 676f0f6765bdaa7d7d760f88
        bodyMarkdown:
          type: string
          minLength: 1
          description: >-
            The content of the reply message in markdown format. Images
            referenced by URL or as base64 data URIs will be automatically
            uploaded and stored.
          example: Thank you for your help!
        messageType:
          type: string
          enum:
            - reply
          description: The type of message. Always "reply" for contact replies.
          example: reply
      required:
        - type
        - bodyMarkdown
        - messageType
      description: Reply from a customer or lead
      title: Contact Reply
    AdminReplyBody:
      type: object
      properties:
        type:
          type: string
          enum:
            - admin
          description: The type of author. Use "admin" for admin replies.
          example: admin
        id:
          type: string
          description: The Featurebase admin ID
          example: 507f1f77bcf86cd799439011
        bodyMarkdown:
          type: string
          minLength: 1
          description: >-
            The content of the reply message in markdown format. Images
            referenced by URL or as base64 data URIs will be automatically
            uploaded and stored.
          example: |-
            I can help you with that!

            Here is a **bold** explanation.
        messageType:
          type: string
          enum:
            - reply
            - note
          description: >-
            The type of message. "reply" is visible to the customer, "note" is
            an internal note only visible to admins.
          example: reply
      required:
        - type
        - id
        - bodyMarkdown
        - messageType
      description: Reply or internal note from an admin
      title: Admin Reply
    ReplyToConversationBody:
      anyOf:
        - $ref: '#/components/schemas/ContactReplyBody'
        - $ref: '#/components/schemas/AdminReplyBody'
      discriminator:
        propertyName: type
        mapping:
          contact: '#/components/schemas/ContactReplyBody'
          admin: '#/components/schemas/AdminReplyBody'
    MarkAsRead:
      type: object
      properties:
        allAdmins:
          type:
            - boolean
            - 'null'
          description: If true, marks all admins with existing readReceipts as read.
          example: true
        adminIds:
          type: array
          items:
            type: string
          maxItems: 255
          description: >-
            Array of admin IDs to mark as read. Only admins with existing
            readReceipts will be updated.
          example:
            - 507f1f77bcf86cd799439011
        allContacts:
          type:
            - boolean
            - 'null'
          description: >-
            If true, marks all contacts (customers and leads) with existing
            readReceipts as read.
          example: true
        contactIds:
          type: array
          items:
            type: string
          maxItems: 255
          description: >-
            Array of contact IDs to mark as read. Only contacts with existing
            readReceipts will be updated.
          example:
            - 676f0f6765bdaa7d7d760f88
      description: Mark the conversation as read for specific admins and/or contacts.
    UpdateConversationBody:
      type: object
      properties:
        actingAdminId:
          type: string
          description: >-
            The admin ID performing this action. Changes will be attributed to
            this admin. If not provided, changes are attributed to the system
            bot user. The admin must be a member of the organization.
          example: 507f1f77bcf86cd799439011
        state:
          type: string
          enum:
            - open
            - closed
            - snoozed
          description: >-
            The state of the conversation. Use "snoozed" with snoozedUntil to
            snooze.
          example: open
        snoozedUntil:
          type:
            - string
            - 'null'
          description: >-
            ISO datetime when the conversation should be unsnoozed. Required
            when state is "snoozed". Must be a future date.
          example: '2025-01-20T10:00:00.000Z'
        adminAssigneeId:
          type:
            - string
            - 'null'
          description: The admin ID to assign the conversation to, or null to unassign.
          example: 507f1f77bcf86cd799439011
        teamAssigneeId:
          type:
            - string
            - 'null'
          description: The team ID to assign the conversation to, or null to unassign.
          example: 507f1f77bcf86cd799439012
        title:
          type: string
          maxLength: 255
          description: The title of the conversation.
          example: Question about pricing
        customAttributes:
          type: object
          additionalProperties: {}
          description: >-
            Custom attributes to set on the conversation. Uses the same
            validation as v1 API.
          example:
            priority_level: high
            category: billing
        markAsRead:
          $ref: '#/components/schemas/MarkAsRead'
    ParticipantIdentifier:
      type: object
      properties:
        id:
          type: string
          description: The Featurebase ID of the contact (customer or lead)
          example: 676f0f6765bdaa7d7d760f88
        userId:
          type: string
          maxLength: 255
          description: The external user ID from your system (matches customer type only)
          example: user_123
        email:
          type: string
          format: email
          description: The email address of the contact (matches customer type only)
          example: john@example.com
      description: >-
        The contact to add as a participant. At least one of id, userId, or
        email is required.
    AddParticipantBody:
      type: object
      properties:
        participant:
          $ref: '#/components/schemas/ParticipantIdentifier'
        actingAdminId:
          type: string
          description: >-
            The admin ID performing this action. If not provided, changes are
            attributed to the system bot user.
          example: 507f1f77bcf86cd799439011
      required:
        - participant
    RemoveParticipantBody:
      type: object
      properties:
        id:
          type: string
          description: The Featurebase ID of the contact (customer or lead) to remove
          example: 676f0f6765bdaa7d7d760f88
        actingAdminId:
          type: string
          description: >-
            The admin ID performing this action. If not provided, changes are
            attributed to the system bot user.
          example: 507f1f77bcf86cd799439011
      required:
        - id
    RedactConversationPartBody:
      type: object
      properties:
        type:
          type: string
          enum:
            - conversation_part
          description: >-
            The type of item to redact. Currently only "conversation_part" is
            supported.
          example: conversation_part
        conversationId:
          type: string
          minLength: 1
          maxLength: 16
          pattern: ^[a-zA-Z0-9]+$
          description: The conversation short ID that contains the part to redact
          example: '12345'
        conversationPartId:
          type: string
          minLength: 1
          maxLength: 16
          pattern: ^[a-zA-Z0-9]+$
          description: The conversation part short ID to redact
          example: '67890'
        actingAdminId:
          type: string
          description: >-
            The admin ID performing this action. If not provided, changes are
            attributed to the system bot user.
          example: 507f1f77bcf86cd799439011
      required:
        - type
        - conversationId
        - conversationPartId
    WebhookRequestConfig:
      type: object
      properties:
        timeoutMs:
          type: integer
          minimum: 1000
          maximum: 30000
          description: Request timeout in milliseconds (1000-30000)
          example: 5000
        headers:
          type: object
          additionalProperties:
            type: string
          description: Custom headers to send with webhook requests
          example:
            X-Custom-Header: value
      required:
        - timeoutMs
    WebhookLastStatus:
      type:
        - object
        - 'null'
      properties:
        code:
          type: integer
          description: HTTP status code from last delivery attempt
          example: 200
        message:
          type: string
          description: Status message from last delivery attempt
          example: Success
        timestamp:
          type: string
          description: ISO timestamp of last status update
          example: '2025-01-15T10:30:00.000Z'
      required:
        - code
        - message
        - timestamp
      description: Last delivery attempt status
    WebhookHealth:
      type: object
      properties:
        lastResponseTime:
          type: number
          description: Last response time in milliseconds
          example: 150
        avgResponseTime:
          type: number
          description: Average response time in milliseconds
          example: 200
        lastSuccessAt:
          type:
            - string
            - 'null'
          description: ISO timestamp of last successful delivery
          example: '2025-01-15T10:30:00.000Z'
        errorsSinceLastSuccess:
          type: integer
          description: Number of errors since last successful delivery
          example: 0
        consecutiveFailures:
          type: integer
          description: Number of consecutive delivery failures
          example: 0
      required:
        - lastResponseTime
        - avgResponseTime
        - lastSuccessAt
        - errorsSinceLastSuccess
        - consecutiveFailures
    Webhook:
      type: object
      properties:
        object:
          type: string
          enum:
            - webhook
          description: Object type identifier
          example: webhook
        id:
          type: string
          description: Unique identifier
          example: 507f1f77bcf86cd799439011
        name:
          type: string
          description: Human-readable webhook name
          example: Production Webhook
        url:
          type: string
          description: Webhook endpoint URL
          example: https://example.com/webhooks
        secret:
          type: string
          description: Webhook signing secret for verifying payloads
          example: whsec_abc123def456ghi789
        description:
          type:
            - string
            - 'null'
          description: Optional description of the webhook purpose
          example: Handles all production events
        topics:
          type: array
          items:
            type: string
            enum:
              - post.created
              - post.updated
              - post.deleted
              - post.voted
              - changelog.published
              - comment.created
              - comment.updated
              - comment.deleted
            description: Webhook event topic
            example: post.created
          description: Array of event topics the webhook subscribes to
          example:
            - post.created
            - post.updated
        status:
          type: string
          enum:
            - active
            - paused
            - suspended
          description: Current status of the webhook
          example: active
        requestConfig:
          $ref: '#/components/schemas/WebhookRequestConfig'
        lastStatus:
          $ref: '#/components/schemas/WebhookLastStatus'
        health:
          $ref: '#/components/schemas/WebhookHealth'
        version:
          type: string
          description: API version for webhook payloads
          example: '1.0'
        createdAt:
          type: string
          description: ISO timestamp when the webhook was created
          example: '2025-01-15T10:30:00.000Z'
        updatedAt:
          type: string
          description: ISO timestamp when the webhook was last updated
          example: '2025-01-15T10:30:00.000Z'
      required:
        - object
        - id
        - name
        - url
        - secret
        - description
        - topics
        - status
        - requestConfig
        - lastStatus
        - health
        - version
        - createdAt
        - updatedAt
    WebhookList:
      type: object
      properties:
        object:
          type: string
          enum:
            - list
          description: Object type identifier
          example: list
        data:
          type: array
          items:
            $ref: '#/components/schemas/Webhook'
          description: Array of webhooks
          example: []
        nextCursor:
          type:
            - string
            - 'null'
          description: Cursor for fetching the next page (cursor-based pagination)
          example: eyJpZCI6IjUwN2YxZjc3YmNmODZjZDc5OTQzOTAxMSJ9
      required:
        - object
        - data
        - nextCursor
    WebhookRequestConfigInput:
      type: object
      properties:
        headers:
          type: object
          additionalProperties:
            type: string
            maxLength: 1024
          description: Custom headers to send with webhook requests (max 10)
          example:
            X-Custom-Header: value
      description: Request configuration for webhook delivery
    CreateWebhookBody:
      type: object
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 255
          description: Human-readable name for the webhook
          example: Production Webhook
        url:
          type: string
          description: Webhook endpoint URL (must be HTTPS)
          example: https://example.com/webhooks
        description:
          type: string
          maxLength: 500
          description: Optional description of the webhook purpose
          example: Handles all production events
        topics:
          type: array
          items:
            type: string
            enum:
              - post.created
              - post.updated
              - post.deleted
              - post.voted
              - changelog.published
              - comment.created
              - comment.updated
              - comment.deleted
            description: Webhook event topic
            example: post.created
          minItems: 1
          description: Array of event topics to subscribe to
          example:
            - post.created
            - post.updated
        requestConfig:
          $ref: '#/components/schemas/WebhookRequestConfigInput'
      required:
        - name
        - url
        - topics
    UpdateWebhookBody:
      type: object
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 255
          description: Human-readable name for the webhook
          example: Production Webhook
        url:
          type: string
          description: Webhook endpoint URL (must be HTTPS)
          example: https://example.com/webhooks
        description:
          type:
            - string
            - 'null'
          maxLength: 500
          description: Optional description of the webhook purpose (null to clear)
          example: Handles all production events
        topics:
          type: array
          items:
            type: string
            enum:
              - post.created
              - post.updated
              - post.deleted
              - post.voted
              - changelog.published
              - comment.created
              - comment.updated
              - comment.deleted
            description: Webhook event topic
            example: post.created
          minItems: 1
          description: Array of event topics to subscribe to
          example:
            - post.created
            - post.updated
        status:
          type: string
          enum:
            - active
            - paused
          description: Set to "active" to reactivate or "paused" to pause webhook delivery
          example: active
        requestConfig:
          $ref: '#/components/schemas/WebhookRequestConfigInput'
    DeletedWebhook:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier of the deleted webhook
          example: 507f1f77bcf86cd799439011
        object:
          type: string
          enum:
            - webhook
          description: Object type identifier
          example: webhook
        deleted:
          type: boolean
          enum:
            - true
          description: Indicates the resource was deleted
          example: true
      required:
        - id
        - object
        - deleted
  parameters:
    FeaturebaseVersion:
      schema:
        $ref: '#/components/schemas/FeaturebaseVersion'
      required: false
      description: >-
        API version for this request. Defaults to your organization's configured
        API version if not specified.
      name: Featurebase-Version
      in: header
paths:
  /v2/boards:
    get:
      operationId: listBoards
      summary: List all boards
      description: >-
        Returns all boards (post categories) for the authenticated organization.


        Boards are containers for posts/feedback. Each board can have different:

        - Access controls (public, private, segment-restricted)

        - Feature toggles (comments, posting enabled)

        - Custom fields


        This endpoint returns all boards without pagination. Organizations
        typically have a small number of boards.
      tags:
        - Boards
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/FeaturebaseVersion'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BoardList'
        '400':
          description: Bad Request - Validation error or invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
        '404':
          description: Not Found - Resource does not exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerError'
  /v2/boards/{id}:
    get:
      operationId: getBoard
      summary: Get a board by ID
      description: |-
        Retrieves a single board by its unique identifier.

        Returns the full board object including all access controls,
        feature toggles, and localization settings.
      tags:
        - Boards
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/FeaturebaseVersion'
        - schema:
            type: string
            description: Board unique identifier
            example: 507f1f77bcf86cd799439011
          required: true
          name: id
          in: path
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Board'
        '400':
          description: |-
            Bad Request

            Possible error codes:
            - `invalid_id`: The board ID format is invalid
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - invalid_request_error
                        description: The type of error returned
                        example: invalid_request_error
                      code:
                        type: string
                        enum:
                          - invalid_id
                        description: Machine-readable error code
                        example: invalid_id
                      message:
                        type: string
                        description: Human-readable error message
                        example: An error occurred
                      param:
                        type: string
                        description: The parameter that caused the error (if applicable)
                        example: id
                      status:
                        type: number
                        enum:
                          - 400
                        description: HTTP status code
                        example: 400
                    required:
                      - type
                      - code
                      - message
                      - status
                required:
                  - error
        '404':
          description: |-
            Not Found

            Possible error codes:
            - `board_not_found`: No board exists with this ID
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - invalid_request_error
                        description: The type of error returned
                        example: invalid_request_error
                      code:
                        type: string
                        enum:
                          - board_not_found
                        description: Machine-readable error code
                        example: board_not_found
                      message:
                        type: string
                        description: Human-readable error message
                        example: An error occurred
                      param:
                        type: string
                        description: The parameter that caused the error (if applicable)
                        example: id
                      status:
                        type: number
                        enum:
                          - 404
                        description: HTTP status code
                        example: 404
                    required:
                      - type
                      - code
                      - message
                      - status
                required:
                  - error
  /v2/posts:
    get:
      operationId: listPosts
      summary: List all posts
      description: >-
        Returns all posts (feedback submissions) for the authenticated
        organization.


        Posts are user-submitted feedback items. Each post belongs to a board
        and can have:

        - Status (in progress, complete, etc.)

        - Tags for categorization

        - Upvotes from users

        - Comments (if enabled)

        - Custom field values


        ### Pagination


        This endpoint uses **cursor-based pagination**:


        - `limit` - Number of posts to return (1-100, default 10)

        - `cursor` - Opaque cursor from a previous response's `nextCursor` field


        **Example:** To paginate through results:

        1. First request: `GET /v2/posts?limit=10`

        2. If `nextCursor` is not null, use it for the next page

        3. Next request: `GET /v2/posts?limit=10&cursor={nextCursor}`


        ### Response Format


        Returns a list object with:

        - `object` - Always "list"

        - `data` - Array of post objects

        - `nextCursor` - Cursor for the next page (null if no more results)


        ### Filtering


        Filter posts using query parameters:

        - `boardId` - Filter by board (category) ID

        - `statusId` - Filter by status ID

        - `tags` - Filter by tag names (can be comma-separated or repeated)

        - `q` - Search query for title/content

        - `inReview` - Include posts pending moderation


        ### Sorting


        Use `sortBy` to sort results:

        - `createdAt` - Sort by creation date (default)

        - `upvotes` - Sort by vote count

        - `trending` - Sort by trending score

        - `recent` - Sort by most recently updated
      tags:
        - Posts
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/FeaturebaseVersion'
        - schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 10
            description: A limit on the number of posts to be returned, between 1 and 100.
            example: 10
          required: false
          name: limit
          in: query
        - schema:
            type: string
            maxLength: 512
            description: >-
              An opaque cursor for pagination. Use the nextCursor value from a
              previous response to fetch the next page of results.
            example: eyJpZCI6IjUwN2YxZjc3YmNmODZjZDc5OTQzOTAxMSJ9
          required: false
          name: cursor
          in: query
        - schema:
            anyOf:
              - type: string
              - type: array
                items:
                  type: string
                maxItems: 50
            description: Filter by board (category) ID(s)
            example: 507f1f77bcf86cd799439011
          required: false
          name: boardId
          in: query
        - schema:
            anyOf:
              - type: string
              - type: array
                items:
                  type: string
                maxItems: 50
            description: Filter by status ID(s)
            example: 507f1f77bcf86cd799439012
          required: false
          name: statusId
          in: query
        - schema:
            anyOf:
              - type: string
                maxLength: 255
              - type: array
                items:
                  type: string
                  maxLength: 255
                maxItems: 50
            description: Filter by tag names
            example:
              - bug
              - feature
          required: false
          name: tags
          in: query
        - schema:
            type: string
            maxLength: 255
            description: Search query to filter posts by title/content
            example: dark mode
          required: false
          name: q
          in: query
        - schema:
            type:
              - boolean
              - 'null'
            description: Include posts that are in review
            example: true
          required: false
          name: inReview
          in: query
        - schema:
            type: string
            enum:
              - createdAt
              - upvotes
              - trending
              - recent
            default: createdAt
            description: Sort order for posts
            example: upvotes
          required: false
          name: sortBy
          in: query
        - schema:
            type: string
            enum:
              - asc
              - desc
            default: desc
            description: Sort direction
            example: desc
          required: false
          name: sortOrder
          in: query
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostList'
        '400':
          description: |-
            Bad Request

            Possible error codes:
            - `invalid_cursor`: The pagination cursor is malformed or expired
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - invalid_request_error
                        description: The type of error returned
                        example: invalid_request_error
                      code:
                        type: string
                        enum:
                          - invalid_cursor
                        description: Machine-readable error code
                        example: invalid_cursor
                      message:
                        type: string
                        description: Human-readable error message
                        example: An error occurred
                      param:
                        type: string
                        description: The parameter that caused the error (if applicable)
                        example: id
                      status:
                        type: number
                        enum:
                          - 400
                        description: HTTP status code
                        example: 400
                    required:
                      - type
                      - code
                      - message
                      - status
                required:
                  - error
    post:
      operationId: createPost
      summary: Create a new post
      description: >-
        Creates a new post (feedback submission) in the specified board.


        ### Required Fields


        - `title` - Post title (minimum 2 characters)

        - `boardId` - Board ID to create the post in


        ### Optional Fields


        - `content` - Post content in HTML format

        - `tags` - Array of tag names to attach

        - `statusId` - Status ID to set (defaults to board's default status)

        - `commentsEnabled` - Whether comments are allowed (default: true)

        - `inReview` - Whether post is pending moderation (default: false)

        - `customFields` - Custom field values as key-value pairs

        - `eta` - Estimated completion date (Unix timestamp or ISO date)

        - `assigneeId` - Admin ID to assign this post to

        - `visibility` - Post-level visibility restriction: 'public' (no
        additional restrictions), 'authorOnly' (only author and admins), or
        'companyOnly' (only users in author's company). Note: even 'public'
        posts are still subject to board-level and organization-level access
        controls.


        ### Author Attribution


        For posts created on behalf of users, use the `author` object:

        - `id` - Featurebase user ID

        - `userId` - External SSO user ID

        - `email` - User's email address

        - `name` - Display name

        - `profilePicture` - Profile picture URL


        Resolution priority: `id` > `userId` > `email` > authenticated user


        ### Backdating (Imports)


        - `createdAt` - Override creation date for importing historical data


        ### Response


        Returns the created post object with all fields populated.
      tags:
        - Posts
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/FeaturebaseVersion'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePostBody'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Post'
        '400':
          description: |-
            Bad Request

            Possible error codes:
            - `invalid_request`: Invalid or missing required fields
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - invalid_request_error
                        description: The type of error returned
                        example: invalid_request_error
                      code:
                        type: string
                        enum:
                          - invalid_request
                        description: Machine-readable error code
                        example: invalid_request
                      message:
                        type: string
                        description: Human-readable error message
                        example: An error occurred
                      param:
                        type: string
                        description: The parameter that caused the error (if applicable)
                        example: id
                      status:
                        type: number
                        enum:
                          - 400
                        description: HTTP status code
                        example: 400
                    required:
                      - type
                      - code
                      - message
                      - status
                required:
                  - error
        '404':
          description: |-
            Not Found

            Possible error codes:
            - `board_not_found`: The specified boardId does not exist
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - invalid_request_error
                        description: The type of error returned
                        example: invalid_request_error
                      code:
                        type: string
                        enum:
                          - board_not_found
                        description: Machine-readable error code
                        example: board_not_found
                      message:
                        type: string
                        description: Human-readable error message
                        example: An error occurred
                      param:
                        type: string
                        description: The parameter that caused the error (if applicable)
                        example: id
                      status:
                        type: number
                        enum:
                          - 404
                        description: HTTP status code
                        example: 404
                    required:
                      - type
                      - code
                      - message
                      - status
                required:
                  - error
  /v2/posts/{id}:
    get:
      operationId: getPost
      summary: Get a post by ID
      description: |-
        Retrieves a single post by its unique identifier.

        Returns the full post object including:
        - Author information
        - Current status
        - Tags
        - Voting stats
        - Engagement metrics
        - Custom field values
      tags:
        - Posts
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/FeaturebaseVersion'
        - schema:
            type: string
            description: Post unique identifier
            example: 507f1f77bcf86cd799439011
          required: true
          name: id
          in: path
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Post'
        '400':
          description: |-
            Bad Request

            Possible error codes:
            - `invalid_id`: The post ID format is invalid
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - invalid_request_error
                        description: The type of error returned
                        example: invalid_request_error
                      code:
                        type: string
                        enum:
                          - invalid_id
                        description: Machine-readable error code
                        example: invalid_id
                      message:
                        type: string
                        description: Human-readable error message
                        example: An error occurred
                      param:
                        type: string
                        description: The parameter that caused the error (if applicable)
                        example: id
                      status:
                        type: number
                        enum:
                          - 400
                        description: HTTP status code
                        example: 400
                    required:
                      - type
                      - code
                      - message
                      - status
                required:
                  - error
        '404':
          description: |-
            Not Found

            Possible error codes:
            - `post_not_found`: No post exists with this ID
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - invalid_request_error
                        description: The type of error returned
                        example: invalid_request_error
                      code:
                        type: string
                        enum:
                          - post_not_found
                        description: Machine-readable error code
                        example: post_not_found
                      message:
                        type: string
                        description: Human-readable error message
                        example: An error occurred
                      param:
                        type: string
                        description: The parameter that caused the error (if applicable)
                        example: id
                      status:
                        type: number
                        enum:
                          - 404
                        description: HTTP status code
                        example: 404
                    required:
                      - type
                      - code
                      - message
                      - status
                required:
                  - error
    patch:
      operationId: updatePost
      summary: Update a post
      description: >-
        Updates an existing post. Only provided fields will be modified.


        ### Updatable Fields


        - `title` - Post title (minimum 2 characters)

        - `content` - Post content in HTML format

        - `boardId` - Move post to a different board

        - `statusId` - Update post status

        - `tags` - Replace existing tags with new set

        - `commentsEnabled` - Enable/disable comments

        - `inReview` - Put post in/out of moderation queue

        - `customFields` - Update custom field values

        - `eta` - Set estimated completion date (null to clear)

        - `createdAt` - Update creation date (for backdating)

        - `assigneeId` - Admin ID to assign this post to (null to unassign)

        - `visibility` - Post-level visibility restriction: 'public' (no
        additional restrictions), 'authorOnly' (only author and admins), or
        'companyOnly' (only users in author's company). Note: even 'public'
        posts are still subject to board-level and organization-level access
        controls.

        - `author` - Change post attribution (id, userId, email, name,
        profilePicture)


        ### Status Update Notifications


        - `sendStatusUpdateEmail` - When changing status, optionally send email
        notification to voters (default: false)


        ### Response


        Returns the updated post object with all fields populated.
      tags:
        - Posts
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/FeaturebaseVersion'
        - schema:
            type: string
            description: Post unique identifier
            example: 507f1f77bcf86cd799439011
          required: true
          name: id
          in: path
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdatePostBody'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Post'
        '400':
          description: |-
            Bad Request

            Possible error codes:
            - `invalid_id`: The post ID format is invalid
            - `invalid_request`: Invalid update parameters
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - invalid_request_error
                        description: The type of error returned
                        example: invalid_request_error
                      code:
                        type: string
                        enum:
                          - invalid_id
                          - invalid_request
                        description: Machine-readable error code
                        example: invalid_id
                      message:
                        type: string
                        description: Human-readable error message
                        example: An error occurred
                      param:
                        type: string
                        description: The parameter that caused the error (if applicable)
                        example: id
                      status:
                        type: number
                        enum:
                          - 400
                        description: HTTP status code
                        example: 400
                    required:
                      - type
                      - code
                      - message
                      - status
                required:
                  - error
        '404':
          description: |-
            Not Found

            Possible error codes:
            - `post_not_found`: No post exists with this ID
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - invalid_request_error
                        description: The type of error returned
                        example: invalid_request_error
                      code:
                        type: string
                        enum:
                          - post_not_found
                        description: Machine-readable error code
                        example: post_not_found
                      message:
                        type: string
                        description: Human-readable error message
                        example: An error occurred
                      param:
                        type: string
                        description: The parameter that caused the error (if applicable)
                        example: id
                      status:
                        type: number
                        enum:
                          - 404
                        description: HTTP status code
                        example: 404
                    required:
                      - type
                      - code
                      - message
                      - status
                required:
                  - error
    delete:
      operationId: deletePost
      summary: Delete a post
      description: |-
        Permanently deletes a post. This action cannot be undone.

        ### What Gets Deleted

        When you delete a post:
        - The post itself is permanently removed
        - All comments on the post are deleted
        - Vote records are removed
        - Any associated notifications are cleared

        ### Response

        Returns a deletion confirmation object with:
        - `id` - The ID of the deleted post
        - `object` - Always "post"
        - `deleted` - Always true

        ### Permissions

        Requires member-level access or higher to delete posts.
      tags:
        - Posts
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/FeaturebaseVersion'
        - schema:
            type: string
            description: Post unique identifier
            example: 507f1f77bcf86cd799439011
          required: true
          name: id
          in: path
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeletedPost'
        '400':
          description: |-
            Bad Request

            Possible error codes:
            - `invalid_id`: The post ID format is invalid
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - invalid_request_error
                        description: The type of error returned
                        example: invalid_request_error
                      code:
                        type: string
                        enum:
                          - invalid_id
                        description: Machine-readable error code
                        example: invalid_id
                      message:
                        type: string
                        description: Human-readable error message
                        example: An error occurred
                      param:
                        type: string
                        description: The parameter that caused the error (if applicable)
                        example: id
                      status:
                        type: number
                        enum:
                          - 400
                        description: HTTP status code
                        example: 400
                    required:
                      - type
                      - code
                      - message
                      - status
                required:
                  - error
        '404':
          description: |-
            Not Found

            Possible error codes:
            - `post_not_found`: No post exists with this ID
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - invalid_request_error
                        description: The type of error returned
                        example: invalid_request_error
                      code:
                        type: string
                        enum:
                          - post_not_found
                        description: Machine-readable error code
                        example: post_not_found
                      message:
                        type: string
                        description: Human-readable error message
                        example: An error occurred
                      param:
                        type: string
                        description: The parameter that caused the error (if applicable)
                        example: id
                      status:
                        type: number
                        enum:
                          - 404
                        description: HTTP status code
                        example: 404
                    required:
                      - type
                      - code
                      - message
                      - status
                required:
                  - error
  /v2/posts/{id}/voters:
    get:
      operationId: listVoters
      summary: List voters on a post
      description: >-
        Returns all voters (upvoters) for a specific post.


        Voters are users who have upvoted the post. Each voter is returned in
        the standard user format with:

        - Basic info: id, name, email, profilePicture

        - User type (admin, customer, guest, etc.)

        - Companies the user belongs to

        - Activity stats: commentsCreated, postsCreated, lastActivity

        - Preferences: subscribedToChangelog, locale, verified


        ### Pagination


        This endpoint uses **cursor-based pagination**:


        - `limit` - Number of voters to return (1-100, default 10)

        - `cursor` - Opaque cursor from a previous response's `nextCursor` field


        **Example:** To paginate through results:

        1. First request: `GET /v2/posts/{id}/voters?limit=10`

        2. If `nextCursor` is not null, use it for the next page

        3. Next request: `GET
        /v2/posts/{id}/voters?limit=10&cursor={nextCursor}`


        ### Response Format


        Returns a list object with:

        - `object` - Always "list"

        - `data` - Array of user objects

        - `nextCursor` - Cursor for the next page (null if no more results)


        ### Permissions


        Requires member-level access or higher.
      tags:
        - Posts
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/FeaturebaseVersion'
        - schema:
            type: string
            description: Post unique identifier
            example: 507f1f77bcf86cd799439011
          required: true
          name: id
          in: path
        - schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 10
            description: A limit on the number of voters to be returned, between 1 and 100.
            example: 10
          required: false
          name: limit
          in: query
        - schema:
            type: string
            maxLength: 512
            description: >-
              An opaque cursor for pagination. Use the nextCursor value from a
              previous response to fetch the next page of results.
            example: eyJpZCI6IjUwN2YxZjc3YmNmODZjZDc5OTQzOTAxMSJ9
          required: false
          name: cursor
          in: query
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserList'
        '400':
          description: |-
            Bad Request

            Possible error codes:
            - `invalid_id`: The post ID format is invalid
            - `invalid_cursor`: The pagination cursor is malformed or expired
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - invalid_request_error
                        description: The type of error returned
                        example: invalid_request_error
                      code:
                        type: string
                        enum:
                          - invalid_id
                          - invalid_cursor
                        description: Machine-readable error code
                        example: invalid_id
                      message:
                        type: string
                        description: Human-readable error message
                        example: An error occurred
                      param:
                        type: string
                        description: The parameter that caused the error (if applicable)
                        example: id
                      status:
                        type: number
                        enum:
                          - 400
                        description: HTTP status code
                        example: 400
                    required:
                      - type
                      - code
                      - message
                      - status
                required:
                  - error
        '404':
          description: |-
            Not Found

            Possible error codes:
            - `post_not_found`: No post exists with this ID
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - invalid_request_error
                        description: The type of error returned
                        example: invalid_request_error
                      code:
                        type: string
                        enum:
                          - post_not_found
                        description: Machine-readable error code
                        example: post_not_found
                      message:
                        type: string
                        description: Human-readable error message
                        example: An error occurred
                      param:
                        type: string
                        description: The parameter that caused the error (if applicable)
                        example: id
                      status:
                        type: number
                        enum:
                          - 404
                        description: HTTP status code
                        example: 404
                    required:
                      - type
                      - code
                      - message
                      - status
                required:
                  - error
    post:
      operationId: addVoter
      summary: Add a voter to a post
      description: >-
        Adds a voter (upvote) to a post.


        ### Voter Identification


        To add a vote on behalf of a user, provide one or more identification
        fields:

        - `id` - Featurebase user ID

        - `userId` - External SSO user ID from your system

        - `email` - User's email address

        - `name` - Display name (used when creating a new user)

        - `profilePicture` - Profile picture URL (used when creating a new user)


        Resolution priority: `id` > `userId` > `email` > authenticated user


        If no fields are provided, the authenticated user's vote is added.


        If the user doesn't exist, a new customer will be created with the
        provided information.


        ### Idempotency


        If the user has already voted on this post, the request succeeds but no
        duplicate vote is added.


        ### Response


        Returns a confirmation object with:

        - `object` - Always "voter"

        - `added` - Always true

        - `id` - The voter's user ID

        - `postId` - The post ID the vote was added to


        ### Permissions


        Requires member-level access or higher.
      tags:
        - Posts
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/FeaturebaseVersion'
        - schema:
            type: string
            description: Post unique identifier
            example: 507f1f77bcf86cd799439011
          required: true
          name: id
          in: path
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddVoterBody'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AddVoterResponse'
        '400':
          description: |-
            Bad Request

            Possible error codes:
            - `invalid_id`: The post ID format is invalid
            - `invalid_request`: Invalid voter identification parameters
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - invalid_request_error
                        description: The type of error returned
                        example: invalid_request_error
                      code:
                        type: string
                        enum:
                          - invalid_id
                          - invalid_request
                        description: Machine-readable error code
                        example: invalid_id
                      message:
                        type: string
                        description: Human-readable error message
                        example: An error occurred
                      param:
                        type: string
                        description: The parameter that caused the error (if applicable)
                        example: id
                      status:
                        type: number
                        enum:
                          - 400
                        description: HTTP status code
                        example: 400
                    required:
                      - type
                      - code
                      - message
                      - status
                required:
                  - error
        '404':
          description: |-
            Not Found

            Possible error codes:
            - `post_not_found`: No post exists with this ID
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - invalid_request_error
                        description: The type of error returned
                        example: invalid_request_error
                      code:
                        type: string
                        enum:
                          - post_not_found
                        description: Machine-readable error code
                        example: post_not_found
                      message:
                        type: string
                        description: Human-readable error message
                        example: An error occurred
                      param:
                        type: string
                        description: The parameter that caused the error (if applicable)
                        example: id
                      status:
                        type: number
                        enum:
                          - 404
                        description: HTTP status code
                        example: 404
                    required:
                      - type
                      - code
                      - message
                      - status
                required:
                  - error
    delete:
      operationId: removeVoter
      summary: Remove a voter from a post
      description: >-
        Removes a voter (upvote) from a post.


        ### Voter Identification


        To remove a vote on behalf of a user, provide one or more identification
        fields:

        - `id` - Featurebase user ID

        - `userId` - External SSO user ID from your system

        - `email` - User's email address


        Resolution priority: `id` > `userId` > `email` > authenticated user


        If no fields are provided, the authenticated user's vote will be
        removed.


        ### Response


        Returns a confirmation object with:

        - `object` - Always "voter"

        - `removed` - Always true

        - `id` - The voter's user ID

        - `postId` - The post ID the vote was removed from


        ### Permissions


        Requires member-level access or higher.
      tags:
        - Posts
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/FeaturebaseVersion'
        - schema:
            type: string
            description: Post unique identifier
            example: 507f1f77bcf86cd799439011
          required: true
          name: id
          in: path
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RemoveVoterBody'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RemoveVoterResponse'
        '400':
          description: |-
            Bad Request

            Possible error codes:
            - `invalid_id`: The post ID format is invalid
            - `invalid_request`: Invalid voter identification parameters
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - invalid_request_error
                        description: The type of error returned
                        example: invalid_request_error
                      code:
                        type: string
                        enum:
                          - invalid_id
                          - invalid_request
                        description: Machine-readable error code
                        example: invalid_id
                      message:
                        type: string
                        description: Human-readable error message
                        example: An error occurred
                      param:
                        type: string
                        description: The parameter that caused the error (if applicable)
                        example: id
                      status:
                        type: number
                        enum:
                          - 400
                        description: HTTP status code
                        example: 400
                    required:
                      - type
                      - code
                      - message
                      - status
                required:
                  - error
        '404':
          description: |-
            Not Found

            Possible error codes:
            - `post_not_found`: No post exists with this ID
            - `voter_not_found`: The user has not voted on this post
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - invalid_request_error
                        description: The type of error returned
                        example: invalid_request_error
                      code:
                        type: string
                        enum:
                          - post_not_found
                          - voter_not_found
                        description: Machine-readable error code
                        example: post_not_found
                      message:
                        type: string
                        description: Human-readable error message
                        example: An error occurred
                      param:
                        type: string
                        description: The parameter that caused the error (if applicable)
                        example: id
                      status:
                        type: number
                        enum:
                          - 404
                        description: HTTP status code
                        example: 404
                    required:
                      - type
                      - code
                      - message
                      - status
                required:
                  - error
  /v2/post_statuses:
    get:
      operationId: listPostStatuses
      summary: List all post statuses
      description: >-
        Returns all post statuses for the authenticated organization.


        Post statuses define workflow stages for posts. Each status has:

        - A display name and color

        - A type indicating the workflow stage (reviewing, unstarted, active,
        completed, canceled)

        - A flag indicating if it's the default status for new posts


        This endpoint returns all post statuses without pagination.
        Organizations typically have a small number of statuses.
      tags:
        - Post Statuses
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/FeaturebaseVersion'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostStatusList'
        '400':
          description: Bad Request - Validation error or invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
        '404':
          description: Not Found - Resource does not exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerError'
  /v2/post_statuses/{id}:
    get:
      operationId: getPostStatus
      summary: Get a post status by ID
      description: >-
        Retrieves a single post status by its unique identifier.


        Returns the full post status object including name, color, type, and
        default flag.
      tags:
        - Post Statuses
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/FeaturebaseVersion'
        - schema:
            type: string
            description: Post status unique identifier
            example: 507f1f77bcf86cd799439011
          required: true
          name: id
          in: path
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostStatus'
        '400':
          description: |-
            Bad Request

            Possible error codes:
            - `invalid_id`: The status ID format is invalid
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - invalid_request_error
                        description: The type of error returned
                        example: invalid_request_error
                      code:
                        type: string
                        enum:
                          - invalid_id
                        description: Machine-readable error code
                        example: invalid_id
                      message:
                        type: string
                        description: Human-readable error message
                        example: An error occurred
                      param:
                        type: string
                        description: The parameter that caused the error (if applicable)
                        example: id
                      status:
                        type: number
                        enum:
                          - 400
                        description: HTTP status code
                        example: 400
                    required:
                      - type
                      - code
                      - message
                      - status
                required:
                  - error
        '404':
          description: |-
            Not Found

            Possible error codes:
            - `resource_not_found`: No post status exists with this ID
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - invalid_request_error
                        description: The type of error returned
                        example: invalid_request_error
                      code:
                        type: string
                        enum:
                          - resource_not_found
                        description: Machine-readable error code
                        example: resource_not_found
                      message:
                        type: string
                        description: Human-readable error message
                        example: An error occurred
                      param:
                        type: string
                        description: The parameter that caused the error (if applicable)
                        example: id
                      status:
                        type: number
                        enum:
                          - 404
                        description: HTTP status code
                        example: 404
                    required:
                      - type
                      - code
                      - message
                      - status
                required:
                  - error
  /v2/comments:
    get:
      operationId: listComments
      summary: List comments
      description: >-
        Returns comments for your organization.


        Comments are threaded discussions. Each comment can have:

        - Author information

        - Voting (upvotes/downvotes)

        - Privacy settings (public/private)

        - Moderation status

        - Parent comment reference for threading


        ### Filtering


        Optionally filter by:

        - `postId` - Get comments for a specific post

        - `changelogId` - Get comments for a specific changelog


        If no filter is provided, returns all comments across the organization.


        ### Pagination


        This endpoint uses **cursor-based pagination**:


        - `limit` - Number of comments to return (1-100, default 10)

        - `cursor` - Opaque cursor from a previous response's `nextCursor` field


        **Example:** To paginate through results:

        1. First request: `GET /v2/comments?postId={id}&limit=10`

        2. If `nextCursor` is not null, use it for the next page

        3. Next request: `GET
        /v2/comments?postId={id}&limit=10&cursor={nextCursor}`


        ### Response Format


        Returns a list object with:

        - `object` - Always "list"

        - `data` - Array of comment objects (flat structure with
        `parentCommentId` for threading)

        - `nextCursor` - Cursor for the next page (null if no more results)


        ### Comment Structure


        Each comment includes:

        - `id` - Unique comment identifier

        - `postId` / `changelogId` - Reference to the parent content

        - `parentCommentId` - Reference to parent comment (null for root
        comments)

        - `content` - Comment content in HTML format

        - `author` - Author information (id, name, profilePicture, type)

        - `upvotes` / `downvotes` / `score` - Voting metrics

        - `isPrivate` - Whether comment is only visible to admins

        - `inReview` - Whether comment is pending moderation

        - `created` / `updated` - Unix timestamps


        ### Additional Filters


        - `privacy` - Filter by privacy: "public", "private", or "all"

        - `inReview` - Filter by moderation status (true/false)


        ### Sorting


        Use `sortBy` to sort results:

        - `best` - Sort by confidence score (default, like Reddit)

        - `top` - Sort by net score (upvotes - downvotes)

        - `new` - Sort by creation date, newest first

        - `old` - Sort by creation date, oldest first
      tags:
        - Comments
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/FeaturebaseVersion'
        - schema:
            type: string
            description: Filter comments by post ID
            example: 507f1f77bcf86cd799439011
          required: false
          name: postId
          in: query
        - schema:
            type: string
            description: Filter comments by changelog ID
            example: 507f1f77bcf86cd799439012
          required: false
          name: changelogId
          in: query
        - schema:
            type: string
            enum:
              - public
              - private
              - all
            description: Filter comments by privacy
            example: public
          required: false
          name: privacy
          in: query
        - schema:
            type:
              - boolean
              - 'null'
            description: Filter by review status
            example: false
          required: false
          name: inReview
          in: query
        - schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 10
            description: Maximum number of comments to return
            example: 10
          required: false
          name: limit
          in: query
        - schema:
            type: string
            maxLength: 512
            description: Cursor for pagination. Use nextCursor from previous response.
            example: eyJpZCI6IjUwN2YxZjc3YmNmODZjZDc5OTQzOTAxMSJ9
          required: false
          name: cursor
          in: query
        - schema:
            type: string
            enum:
              - best
              - top
              - new
              - old
            default: best
            description: Sort order for comments
            example: best
          required: false
          name: sortBy
          in: query
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommentList'
        '400':
          description: |-
            Bad Request

            Possible error codes:
            - `invalid_cursor`: The pagination cursor is malformed or expired
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - invalid_request_error
                        description: The type of error returned
                        example: invalid_request_error
                      code:
                        type: string
                        enum:
                          - invalid_cursor
                        description: Machine-readable error code
                        example: invalid_cursor
                      message:
                        type: string
                        description: Human-readable error message
                        example: An error occurred
                      param:
                        type: string
                        description: The parameter that caused the error (if applicable)
                        example: id
                      status:
                        type: number
                        enum:
                          - 400
                        description: HTTP status code
                        example: 400
                    required:
                      - type
                      - code
                      - message
                      - status
                required:
                  - error
        '404':
          description: |-
            Not Found

            Possible error codes:
            - `post_not_found`: The specified post or changelog was not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - invalid_request_error
                        description: The type of error returned
                        example: invalid_request_error
                      code:
                        type: string
                        enum:
                          - post_not_found
                        description: Machine-readable error code
                        example: post_not_found
                      message:
                        type: string
                        description: Human-readable error message
                        example: An error occurred
                      param:
                        type: string
                        description: The parameter that caused the error (if applicable)
                        example: id
                      status:
                        type: number
                        enum:
                          - 404
                        description: HTTP status code
                        example: 404
                    required:
                      - type
                      - code
                      - message
                      - status
                required:
                  - error
    post:
      operationId: createComment
      summary: Create a new comment
      description: >-
        Creates a new comment or reply to an existing comment.


        You can create a comment for a post or changelog. Comments support:

        - HTML content (images are automatically uploaded to our storage)

        - Threading (replies via `parentCommentId`)

        - Privacy controls (private comments visible only to admins)

        - Author attribution (post on behalf of users)


        ### Required Fields


        - `content` - Comment content in HTML format

        - `postId` OR `changelogId` - One is required to specify the target


        ### Optional Fields


        - `parentCommentId` - Create a reply to an existing comment

        - `isPrivate` - Make comment visible only to admins (default: false)

        - `sendNotification` - Notify voters about the comment (default: true)

        - `author` - Post comment under a specific user (uses authenticated user
        if not provided)

        - `createdAt` - Backdate creation (useful for imports)


        ### Author Object


        The `author` field supports multiple identification methods:

        - `id` - Featurebase user ID (direct reference)

        - `userId` - External user ID from your system (via SSO)

        - `email` - Email address (finds existing or creates new user)

        - `name` - Display name (used with email for new users)

        - `profilePicture` - Profile picture URL


        If no author is provided, the comment is posted under the authenticated
        user.


        ### Content Format


        Content should be formatted as HTML. For images:

        - External URLs in `img src` attributes are automatically pulled into
        our storage

        - Base64 encoded data URIs (`data:image/...`) are also supported and
        processed


        ### Response


        Returns the created comment object with all fields populated, including:

        - `id` - Unique comment identifier

        - `author` - Author information

        - Voting stats and timestamps


        ### Errors


        - `400` - Invalid input (missing required fields, invalid IDs)

        - `403` - Commenting disabled or not authorized

        - `404` - Post/changelog not found or parent comment not found
      tags:
        - Comments
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/FeaturebaseVersion'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCommentBody'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Comment'
        '400':
          description: |-
            Bad Request

            Possible error codes:
            - `invalid_request`: Invalid or missing required fields
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - invalid_request_error
                        description: The type of error returned
                        example: invalid_request_error
                      code:
                        type: string
                        enum:
                          - invalid_request
                        description: Machine-readable error code
                        example: invalid_request
                      message:
                        type: string
                        description: Human-readable error message
                        example: An error occurred
                      param:
                        type: string
                        description: The parameter that caused the error (if applicable)
                        example: id
                      status:
                        type: number
                        enum:
                          - 400
                        description: HTTP status code
                        example: 400
                    required:
                      - type
                      - code
                      - message
                      - status
                required:
                  - error
        '403':
          description: |-
            Forbidden

            Possible error codes:
            - `feature_disabled`: Commenting is disabled on this board
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - authorization_error
                        description: The type of error returned
                        example: authorization_error
                      code:
                        type: string
                        enum:
                          - feature_disabled
                        description: Machine-readable error code
                        example: feature_disabled
                      message:
                        type: string
                        description: Human-readable error message
                        example: An error occurred
                      param:
                        type: string
                        description: The parameter that caused the error (if applicable)
                        example: id
                      status:
                        type: number
                        enum:
                          - 403
                        description: HTTP status code
                        example: 403
                    required:
                      - type
                      - code
                      - message
                      - status
                required:
                  - error
        '404':
          description: |-
            Not Found

            Possible error codes:
            - `post_not_found`: The specified post or changelog was not found
            - `comment_not_found`: The parent comment was not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - invalid_request_error
                        description: The type of error returned
                        example: invalid_request_error
                      code:
                        type: string
                        enum:
                          - post_not_found
                          - comment_not_found
                        description: Machine-readable error code
                        example: post_not_found
                      message:
                        type: string
                        description: Human-readable error message
                        example: An error occurred
                      param:
                        type: string
                        description: The parameter that caused the error (if applicable)
                        example: id
                      status:
                        type: number
                        enum:
                          - 404
                        description: HTTP status code
                        example: 404
                    required:
                      - type
                      - code
                      - message
                      - status
                required:
                  - error
  /v2/comments/{id}:
    get:
      operationId: getComment
      summary: Get a comment by ID
      description: |-
        Retrieves a single comment by its unique identifier.

        Returns the full comment object including:
        - Author information
        - Voting stats (upvotes, downvotes, score)
        - Privacy and moderation status
        - Threading information (parentCommentId)
        - Timestamps

        ### Response

        Returns a comment object with all fields populated.

        ### Errors

        - `400` - Invalid comment ID format
        - `404` - Comment not found or doesn't belong to your organization
      tags:
        - Comments
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/FeaturebaseVersion'
        - schema:
            type: string
            description: Comment unique identifier
            example: 507f1f77bcf86cd799439011
          required: true
          name: id
          in: path
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Comment'
        '400':
          description: |-
            Bad Request

            Possible error codes:
            - `invalid_id`: The comment ID format is invalid
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - invalid_request_error
                        description: The type of error returned
                        example: invalid_request_error
                      code:
                        type: string
                        enum:
                          - invalid_id
                        description: Machine-readable error code
                        example: invalid_id
                      message:
                        type: string
                        description: Human-readable error message
                        example: An error occurred
                      param:
                        type: string
                        description: The parameter that caused the error (if applicable)
                        example: id
                      status:
                        type: number
                        enum:
                          - 400
                        description: HTTP status code
                        example: 400
                    required:
                      - type
                      - code
                      - message
                      - status
                required:
                  - error
        '404':
          description: |-
            Not Found

            Possible error codes:
            - `comment_not_found`: No comment exists with this ID
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - invalid_request_error
                        description: The type of error returned
                        example: invalid_request_error
                      code:
                        type: string
                        enum:
                          - comment_not_found
                        description: Machine-readable error code
                        example: comment_not_found
                      message:
                        type: string
                        description: Human-readable error message
                        example: An error occurred
                      param:
                        type: string
                        description: The parameter that caused the error (if applicable)
                        example: id
                      status:
                        type: number
                        enum:
                          - 404
                        description: HTTP status code
                        example: 404
                    required:
                      - type
                      - code
                      - message
                      - status
                required:
                  - error
    patch:
      operationId: updateComment
      summary: Update a comment
      description: >-
        Updates an existing comment by its unique identifier.


        You can update:

        - **content** - Comment text (HTML format)

        - **isPrivate** - Privacy status (admin-only visibility)

        - **isPinned** - Pinned status (displayed at top)

        - **inReview** - Moderation status


        ### Content Format


        Content should be formatted as HTML. For images:

        - External URLs in `img src` attributes are automatically pulled into
        our storage

        - Base64 encoded data URIs (`data:image/...`) are also supported and
        processed


        ### Permissions


        - Comment authors can update their own comment content

        - Admin permissions required for:
          - `isPrivate` - Requires `manage_comments_private` permission
          - `isPinned` - Requires `set_comment_pinned` permission
          - `inReview` - Requires `moderate_comments` permission
          - Updating other users' comments - Requires `moderate_comments` permission

        ### Response


        Returns the updated comment object with all fields populated.


        ### Errors


        - `400` - Invalid comment ID format or input

        - `403` - Not authorized to update this comment

        - `404` - Comment not found
      tags:
        - Comments
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/FeaturebaseVersion'
        - schema:
            type: string
            description: Comment unique identifier
            example: 507f1f77bcf86cd799439011
          required: true
          name: id
          in: path
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateCommentBody'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Comment'
        '400':
          description: |-
            Bad Request

            Possible error codes:
            - `invalid_id`: The comment ID format is invalid
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - invalid_request_error
                        description: The type of error returned
                        example: invalid_request_error
                      code:
                        type: string
                        enum:
                          - invalid_id
                        description: Machine-readable error code
                        example: invalid_id
                      message:
                        type: string
                        description: Human-readable error message
                        example: An error occurred
                      param:
                        type: string
                        description: The parameter that caused the error (if applicable)
                        example: id
                      status:
                        type: number
                        enum:
                          - 400
                        description: HTTP status code
                        example: 400
                    required:
                      - type
                      - code
                      - message
                      - status
                required:
                  - error
        '404':
          description: |-
            Not Found

            Possible error codes:
            - `comment_not_found`: No comment exists with this ID
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - invalid_request_error
                        description: The type of error returned
                        example: invalid_request_error
                      code:
                        type: string
                        enum:
                          - comment_not_found
                        description: Machine-readable error code
                        example: comment_not_found
                      message:
                        type: string
                        description: Human-readable error message
                        example: An error occurred
                      param:
                        type: string
                        description: The parameter that caused the error (if applicable)
                        example: id
                      status:
                        type: number
                        enum:
                          - 404
                        description: HTTP status code
                        example: 404
                    required:
                      - type
                      - code
                      - message
                      - status
                required:
                  - error
    delete:
      operationId: deleteComment
      summary: Delete a comment
      description: >-
        Deletes a comment by its unique identifier.


        ### Deletion Behavior


        - **Comments with replies**: Soft delete
          - Content is replaced with "[deleted]"
          - Author information is anonymized
          - Comment remains visible to maintain conversation context
          - Votes and scores are reset to 0

        - **Comments without replies**: Hard delete
          - Comment is permanently removed from the database
          - All associated data is deleted

        ### Permissions


        - Comment authors can delete their own comments

        - Admins can delete any comment (subject to permissions)

        - Lite seat admins can only delete their own comments

        - Non-authors require `manage_comments` or `manage_comments_private`
        permission


        ### Response


        Returns a deletion confirmation:


        ```json

        {
          "id": "507f1f77bcf86cd799439011",
          "object": "comment",
          "deleted": true
        }

        ```


        ### Errors


        - `400` - Invalid comment ID format

        - `403` - Not authorized to delete this comment

        - `404` - Comment not found or doesn't belong to your organization
      tags:
        - Comments
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/FeaturebaseVersion'
        - schema:
            type: string
            description: Comment unique identifier
            example: 507f1f77bcf86cd799439011
          required: true
          name: id
          in: path
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeletedComment'
        '400':
          description: |-
            Bad Request

            Possible error codes:
            - `invalid_id`: The comment ID format is invalid
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - invalid_request_error
                        description: The type of error returned
                        example: invalid_request_error
                      code:
                        type: string
                        enum:
                          - invalid_id
                        description: Machine-readable error code
                        example: invalid_id
                      message:
                        type: string
                        description: Human-readable error message
                        example: An error occurred
                      param:
                        type: string
                        description: The parameter that caused the error (if applicable)
                        example: id
                      status:
                        type: number
                        enum:
                          - 400
                        description: HTTP status code
                        example: 400
                    required:
                      - type
                      - code
                      - message
                      - status
                required:
                  - error
        '404':
          description: |-
            Not Found

            Possible error codes:
            - `comment_not_found`: No comment exists with this ID
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - invalid_request_error
                        description: The type of error returned
                        example: invalid_request_error
                      code:
                        type: string
                        enum:
                          - comment_not_found
                        description: Machine-readable error code
                        example: comment_not_found
                      message:
                        type: string
                        description: Human-readable error message
                        example: An error occurred
                      param:
                        type: string
                        description: The parameter that caused the error (if applicable)
                        example: id
                      status:
                        type: number
                        enum:
                          - 404
                        description: HTTP status code
                        example: 404
                    required:
                      - type
                      - code
                      - message
                      - status
                required:
                  - error
  /v2/comment:
    delete:
      operationId: deleteCommentClover
      summary: Delete a comment
      description: >-
        Deletes a comment using the legacy Clover API format.


        This endpoint accepts the comment ID in the request body instead of the
        route parameter.


        ### Request Body


        ```json

        {
          "id": "507f1f77bcf86cd799439011"
        }

        ```


        ### Deletion Behavior


        - **Comments with replies**: Soft delete
          - Content is replaced with "[deleted]"
          - Author information is anonymized
          - Comment remains visible to maintain conversation context
          - Votes and scores are reset to 0

        - **Comments without replies**: Hard delete
          - Comment is permanently removed from the database
          - All associated data is deleted

        ### Permissions


        - Comment authors can delete their own comments

        - Admins can delete any comment (subject to permissions)

        - Lite seat admins can only delete their own comments

        - Non-authors require `manage_comments` or `manage_comments_private`
        permission


        ### Response


        Returns a success confirmation (Clover format):


        ```json

        {
          "success": true
        }

        ```


        Note: Nova API returns `{ id, object: "comment", deleted: true }`, but
        Clover transformer converts it to `{ success: true }` for backwards
        compatibility.


        ### Errors


        - `400` - Invalid comment ID format or missing ID in body

        - `403` - Not authorized to delete this comment

        - `404` - Comment not found or doesn't belong to your organization
      tags:
        - Comments
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/FeaturebaseVersion'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                id:
                  type: string
                  description: Comment ID
                  example: 507f1f77bcf86cd799439011
              required:
                - id
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                required:
                  - success
        '400':
          description: |-
            Bad Request

            Possible error codes:
            - `invalid_id`: The comment ID format is invalid
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - invalid_request_error
                        description: The type of error returned
                        example: invalid_request_error
                      code:
                        type: string
                        enum:
                          - invalid_id
                        description: Machine-readable error code
                        example: invalid_id
                      message:
                        type: string
                        description: Human-readable error message
                        example: An error occurred
                      param:
                        type: string
                        description: The parameter that caused the error (if applicable)
                        example: id
                      status:
                        type: number
                        enum:
                          - 400
                        description: HTTP status code
                        example: 400
                    required:
                      - type
                      - code
                      - message
                      - status
                required:
                  - error
        '404':
          description: |-
            Not Found

            Possible error codes:
            - `comment_not_found`: No comment exists with this ID
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - invalid_request_error
                        description: The type of error returned
                        example: invalid_request_error
                      code:
                        type: string
                        enum:
                          - comment_not_found
                        description: Machine-readable error code
                        example: comment_not_found
                      message:
                        type: string
                        description: Human-readable error message
                        example: An error occurred
                      param:
                        type: string
                        description: The parameter that caused the error (if applicable)
                        example: id
                      status:
                        type: number
                        enum:
                          - 404
                        description: HTTP status code
                        example: 404
                    required:
                      - type
                      - code
                      - message
                      - status
                required:
                  - error
  /v2/changelogs:
    get:
      operationId: listChangelogs
      summary: List all changelogs
      description: >-
        Returns all changelogs for the authenticated organization.


        Changelogs are release notes and updates that keep users informed about
        new features, improvements, and bug fixes. Each changelog can have:

        - Multiple translations (locales)

        - Categories for organization

        - Featured images

        - Scheduled publishing


        ### Pagination


        This endpoint uses **cursor-based pagination**:


        - `limit` - Number of changelogs to return (1-100, default 10)

        - `cursor` - Opaque cursor from a previous response's `nextCursor` field


        **Example:** To paginate through results:

        1. First request: `GET /v2/changelogs?limit=10`

        2. If `nextCursor` is not null, use it for the next page

        3. Next request: `GET /v2/changelogs?limit=10&cursor={nextCursor}`


        ### Response Format


        Returns a list object with:

        - `object` - Always "list"

        - `data` - Array of changelog objects

        - `nextCursor` - Cursor for the next page (null if no more results)


        ### Filtering


        Filter changelogs using query parameters:

        - `id` - Find a specific changelog by ID or slug

        - `q` - Search query for title/content

        - `categories` - Filter by category names

        - `locale` - Get changelogs in a specific locale (defaults to org
        default)

        - `state` - Filter by state: `live`, `draft`, or `all`

        - `startDate` - Include changelogs dated on or after this date

        - `endDate` - Include changelogs dated on or before this date


        ### Sorting


        Results are sorted by date (descending by default):

        - `sortBy` - Field to sort by (currently only `date`)

        - `sortOrder` - Sort direction: `asc` or `desc` (default: `desc`)
      tags:
        - Changelogs
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/FeaturebaseVersion'
        - schema:
            type: string
            description: Find changelog by its id (also accepts slug)
            example: 6457e3ff70afca5d8c27dccc
          required: false
          name: id
          in: query
        - schema:
            type: string
            maxLength: 255
            description: Search for changelogs by title or content
            example: new feature
          required: false
          name: q
          in: query
        - schema:
            anyOf:
              - type: string
                maxLength: 255
              - type: array
                items:
                  type: string
                  maxLength: 255
                maxItems: 50
            description: Filter changelogs by category names (single value or array)
            example:
              - New
              - Fixed
          required: false
          name: categories
          in: query
        - schema:
            type: string
            enum:
              - bn
              - bs
              - pt-BR
              - bg
              - ca
              - hr
              - cs
              - da
              - nl
              - en
              - et
              - fi
              - fr
              - de
              - el
              - hi
              - hu
              - id
              - it
              - ja
              - ko
              - lv
              - lt
              - ms
              - mn
              - nb
              - pl
              - pt
              - ro
              - ru
              - sr
              - zh-CN
              - sk
              - sl
              - es
              - sw
              - sv
              - th
              - zh-TW
              - tr
              - uk
              - vi
            description: >-
              The locale of the changelogs. Defaults to the organization default
              locale.
            example: en
          required: false
          name: locale
          in: query
        - schema:
            type: string
            enum:
              - draft
              - live
              - all
            default: live
            description: >-
              The state of the changelog. Use "all" to get both draft and live
              changelogs.
            example: live
          required: false
          name: state
          in: query
        - schema:
            type:
              - string
              - 'null'
            description: Include Changelogs dated on or after the specified start date
            example: '2024-01-01'
          required: false
          name: startDate
          in: query
        - schema:
            type:
              - string
              - 'null'
            description: Include Changelogs dated on or before the specified end date
            example: '2024-12-31'
          required: false
          name: endDate
          in: query
        - schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 10
            description: Maximum number of changelogs to return
            example: 10
          required: false
          name: limit
          in: query
        - schema:
            type: string
            maxLength: 512
            description: Cursor for pagination. Use nextCursor from previous response.
            example: eyJpZCI6IjUwN2YxZjc3YmNmODZjZDc5OTQzOTAxMSJ9
          required: false
          name: cursor
          in: query
        - schema:
            type: string
            enum:
              - date
            default: date
            description: Field to sort by
            example: date
          required: false
          name: sortBy
          in: query
        - schema:
            type: string
            enum:
              - asc
              - desc
            default: desc
            description: Sort direction
            example: desc
          required: false
          name: sortOrder
          in: query
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChangelogList'
        '400':
          description: |-
            Bad Request

            Possible error codes:
            - `invalid_cursor`: The pagination cursor is malformed or expired
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - invalid_request_error
                        description: The type of error returned
                        example: invalid_request_error
                      code:
                        type: string
                        enum:
                          - invalid_cursor
                        description: Machine-readable error code
                        example: invalid_cursor
                      message:
                        type: string
                        description: Human-readable error message
                        example: An error occurred
                      param:
                        type: string
                        description: The parameter that caused the error (if applicable)
                        example: id
                      status:
                        type: number
                        enum:
                          - 400
                        description: HTTP status code
                        example: 400
                    required:
                      - type
                      - code
                      - message
                      - status
                required:
                  - error
    post:
      operationId: createChangelog
      summary: Create a new changelog
      description: >-
        Creates a new changelog for the authenticated organization.


        ### Required Fields


        - `title` - The title of the changelog


        ### Content


        Provide content in one of two formats (at least one is required):

        - `htmlContent` - HTML content of the changelog

        - `markdownContent` - Markdown content of the changelog


        **Note:** For images in content, you can use:

        - External URLs in img src attributes (automatically uploaded to our
        storage)

        - Base64 encoded data URIs (data:image/...) which are processed and
        stored


        ### Optional Fields


        - `categories` - Array of category names (e.g., ["New", "Fixed",
        "Improved"])

        - `featuredImage` - URL of the featured image (external URLs are
        uploaded to our storage)

        - `allowedSegmentIds` - Array of segment IDs that are allowed to view
        the changelog

        - `locale` - The locale of the changelog (defaults to organization
        default)

        - `date` - The date of the changelog

        - `state` - The state of the changelog: `draft` (default) or `live`


        ### Response


        Returns the created changelog object.
      tags:
        - Changelogs
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/FeaturebaseVersion'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateChangelogBody'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Changelog'
        '400':
          description: |-
            Bad Request

            Possible error codes:
            - `invalid_request`: Invalid or missing required fields
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - invalid_request_error
                        description: The type of error returned
                        example: invalid_request_error
                      code:
                        type: string
                        enum:
                          - invalid_request
                        description: Machine-readable error code
                        example: invalid_request
                      message:
                        type: string
                        description: Human-readable error message
                        example: An error occurred
                      param:
                        type: string
                        description: The parameter that caused the error (if applicable)
                        example: id
                      status:
                        type: number
                        enum:
                          - 400
                        description: HTTP status code
                        example: 400
                    required:
                      - type
                      - code
                      - message
                      - status
                required:
                  - error
  /v2/changelogs/{id}:
    get:
      operationId: getChangelog
      summary: Get a changelog by ID
      description: >-
        Retrieves a single changelog by its unique identifier or slug.


        Returns the full changelog object including:

        - Title and content (in HTML and markdown formats)

        - Featured image

        - Publication date

        - Categories

        - Comment count

        - Email notification status


        ### Localization


        The changelog content is returned in the organization's default locale.

        If the changelog doesn't exist in the default locale, the first
        available locale is used.


        ### State


        Both published (`live`) and draft changelogs can be retrieved.

        The `state` field indicates the current publication status.
      tags:
        - Changelogs
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/FeaturebaseVersion'
        - schema:
            type: string
            description: Changelog unique identifier
            example: 507f1f77bcf86cd799439011
          required: true
          name: id
          in: path
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Changelog'
        '400':
          description: |-
            Bad Request

            Possible error codes:
            - `invalid_id`: The changelog ID format is invalid
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - invalid_request_error
                        description: The type of error returned
                        example: invalid_request_error
                      code:
                        type: string
                        enum:
                          - invalid_id
                        description: Machine-readable error code
                        example: invalid_id
                      message:
                        type: string
                        description: Human-readable error message
                        example: An error occurred
                      param:
                        type: string
                        description: The parameter that caused the error (if applicable)
                        example: id
                      status:
                        type: number
                        enum:
                          - 400
                        description: HTTP status code
                        example: 400
                    required:
                      - type
                      - code
                      - message
                      - status
                required:
                  - error
        '404':
          description: |-
            Not Found

            Possible error codes:
            - `changelog_not_found`: No changelog exists with this ID
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - invalid_request_error
                        description: The type of error returned
                        example: invalid_request_error
                      code:
                        type: string
                        enum:
                          - changelog_not_found
                        description: Machine-readable error code
                        example: changelog_not_found
                      message:
                        type: string
                        description: Human-readable error message
                        example: An error occurred
                      param:
                        type: string
                        description: The parameter that caused the error (if applicable)
                        example: id
                      status:
                        type: number
                        enum:
                          - 404
                        description: HTTP status code
                        example: 404
                    required:
                      - type
                      - code
                      - message
                      - status
                required:
                  - error
    patch:
      operationId: updateChangelog
      summary: Update a changelog
      description: >-
        Updates an existing changelog by its unique identifier.


        You can update:

        - **title** - The changelog title

        - **htmlContent** - HTML content (one of htmlContent or markdownContent)

        - **markdownContent** - Markdown content (one of htmlContent or
        markdownContent)

        - **categories** - Array of category names

        - **featuredImage** - Featured image URL

        - **allowedSegmentIds** - Segment IDs for access control

        - **date** - The date of the changelog


        ### Content Format


        Provide content in one of two formats:

        - `htmlContent` - HTML content of the changelog

        - `markdownContent` - Markdown content of the changelog


        **Note:** For images in content, you can use:

        - External URLs in img src attributes (automatically uploaded to our
        storage)

        - Base64 encoded data URIs (data:image/...) which are processed and
        stored


        ### Categories


        Provide category names as an array. The categories must already exist in
        your organization.


        **Example:** `["New", "Fixed", "Improved"]`


        ### Response


        Returns the updated changelog object with all fields populated.


        ### Errors


        - `400` - Invalid changelog ID format or invalid input

        - `404` - Changelog not found or doesn't belong to your organization
      tags:
        - Changelogs
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/FeaturebaseVersion'
        - schema:
            type: string
            description: Changelog unique identifier
            example: 507f1f77bcf86cd799439011
          required: true
          name: id
          in: path
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateChangelogBody'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Changelog'
        '400':
          description: |-
            Bad Request

            Possible error codes:
            - `invalid_id`: The changelog ID format is invalid
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - invalid_request_error
                        description: The type of error returned
                        example: invalid_request_error
                      code:
                        type: string
                        enum:
                          - invalid_id
                        description: Machine-readable error code
                        example: invalid_id
                      message:
                        type: string
                        description: Human-readable error message
                        example: An error occurred
                      param:
                        type: string
                        description: The parameter that caused the error (if applicable)
                        example: id
                      status:
                        type: number
                        enum:
                          - 400
                        description: HTTP status code
                        example: 400
                    required:
                      - type
                      - code
                      - message
                      - status
                required:
                  - error
        '404':
          description: |-
            Not Found

            Possible error codes:
            - `changelog_not_found`: No changelog exists with this ID
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - invalid_request_error
                        description: The type of error returned
                        example: invalid_request_error
                      code:
                        type: string
                        enum:
                          - changelog_not_found
                        description: Machine-readable error code
                        example: changelog_not_found
                      message:
                        type: string
                        description: Human-readable error message
                        example: An error occurred
                      param:
                        type: string
                        description: The parameter that caused the error (if applicable)
                        example: id
                      status:
                        type: number
                        enum:
                          - 404
                        description: HTTP status code
                        example: 404
                    required:
                      - type
                      - code
                      - message
                      - status
                required:
                  - error
    delete:
      operationId: deleteChangelog
      summary: Delete a changelog
      description: >-
        Deletes a changelog by its unique identifier.


        ### Deletion Behavior


        The changelog and all associated comments are permanently deleted. This
        action cannot be undone.


        ### Permissions


        Only organization admins can delete changelogs.


        ### Response


        Returns a deletion confirmation:


        ```json

        {
          "id": "6457e3ff70afca5d8c27dccc",
          "object": "changelog",
          "deleted": true
        }

        ```


        ### Errors


        - `400` - Invalid changelog ID format

        - `404` - Changelog not found or doesn't belong to your organization
      tags:
        - Changelogs
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/FeaturebaseVersion'
        - schema:
            type: string
            description: Changelog unique identifier
            example: 507f1f77bcf86cd799439011
          required: true
          name: id
          in: path
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeletedChangelog'
        '400':
          description: |-
            Bad Request

            Possible error codes:
            - `invalid_id`: The changelog ID format is invalid
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - invalid_request_error
                        description: The type of error returned
                        example: invalid_request_error
                      code:
                        type: string
                        enum:
                          - invalid_id
                        description: Machine-readable error code
                        example: invalid_id
                      message:
                        type: string
                        description: Human-readable error message
                        example: An error occurred
                      param:
                        type: string
                        description: The parameter that caused the error (if applicable)
                        example: id
                      status:
                        type: number
                        enum:
                          - 400
                        description: HTTP status code
                        example: 400
                    required:
                      - type
                      - code
                      - message
                      - status
                required:
                  - error
        '404':
          description: |-
            Not Found

            Possible error codes:
            - `changelog_not_found`: No changelog exists with this ID
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - invalid_request_error
                        description: The type of error returned
                        example: invalid_request_error
                      code:
                        type: string
                        enum:
                          - changelog_not_found
                        description: Machine-readable error code
                        example: changelog_not_found
                      message:
                        type: string
                        description: Human-readable error message
                        example: An error occurred
                      param:
                        type: string
                        description: The parameter that caused the error (if applicable)
                        example: id
                      status:
                        type: number
                        enum:
                          - 404
                        description: HTTP status code
                        example: 404
                    required:
                      - type
                      - code
                      - message
                      - status
                required:
                  - error
  /v2/changelogs/{id}/publish:
    post:
      operationId: publishChangelog
      summary: Publish a changelog
      description: >-
        Publishes a changelog and optionally sends an email notification to
        subscribers.


        ### Optional Fields


        - `sendEmail` - Whether to send an email notification to subscribers
        (default: false)

        - `locales` - Array of locales to publish. An empty array publishes to
        all available locales

        - `scheduledDate` - A future date/time when the changelog should be
        published


        ### Scheduling


        If `scheduledDate` is provided:

        - Must be a future date

        - The changelog will be scheduled for publishing at that time

        - Any existing scheduled publish for the same locales will be cancelled
        and replaced


        ### Email Notifications


        If `sendEmail` is true:

        - Email notifications are sent to all subscribers in the published
        locales

        - Emails are only sent once per locale (won't resend on republish)


        ### Response


        Returns a success confirmation:


        ```json

        {
          "success": true,
          "state": "published"
        }

        ```


        Or for scheduled publishes:


        ```json

        {
          "success": true,
          "state": "scheduled"
        }

        ```


        ### Errors


        - `400` - Invalid changelog ID or scheduled date is not in the future

        - `404` - Changelog not found or doesn't belong to your organization
      tags:
        - Changelogs
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/FeaturebaseVersion'
        - schema:
            type: string
            description: Changelog unique identifier
            example: 507f1f77bcf86cd799439011
          required: true
          name: id
          in: path
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PublishChangelogBody'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublishUnpublishSuccess'
        '400':
          description: |-
            Bad Request

            Possible error codes:
            - `invalid_id`: The changelog ID format is invalid
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - invalid_request_error
                        description: The type of error returned
                        example: invalid_request_error
                      code:
                        type: string
                        enum:
                          - invalid_id
                        description: Machine-readable error code
                        example: invalid_id
                      message:
                        type: string
                        description: Human-readable error message
                        example: An error occurred
                      param:
                        type: string
                        description: The parameter that caused the error (if applicable)
                        example: id
                      status:
                        type: number
                        enum:
                          - 400
                        description: HTTP status code
                        example: 400
                    required:
                      - type
                      - code
                      - message
                      - status
                required:
                  - error
        '404':
          description: |-
            Not Found

            Possible error codes:
            - `changelog_not_found`: No changelog exists with this ID
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - invalid_request_error
                        description: The type of error returned
                        example: invalid_request_error
                      code:
                        type: string
                        enum:
                          - changelog_not_found
                        description: Machine-readable error code
                        example: changelog_not_found
                      message:
                        type: string
                        description: Human-readable error message
                        example: An error occurred
                      param:
                        type: string
                        description: The parameter that caused the error (if applicable)
                        example: id
                      status:
                        type: number
                        enum:
                          - 404
                        description: HTTP status code
                        example: 404
                    required:
                      - type
                      - code
                      - message
                      - status
                required:
                  - error
  /v2/changelogs/{id}/unpublish:
    post:
      operationId: unpublishChangelog
      summary: Unpublish a changelog
      description: >-
        Unpublishes a changelog, removing it from public view.


        ### Optional Fields


        - `locales` - Array of locales to unpublish from. An empty array
        unpublishes from all locales


        ### Behavior


        - The changelog content is preserved (reverts to draft state)

        - Any scheduled publishes for the specified locales are cancelled

        - The changelog can be re-published later


        ### Response


        Returns a success confirmation:


        ```json

        {
          "success": true,
          "state": "unpublished"
        }

        ```


        ### Errors


        - `400` - Invalid changelog ID format

        - `404` - Changelog not found or doesn't belong to your organization
      tags:
        - Changelogs
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/FeaturebaseVersion'
        - schema:
            type: string
            description: Changelog unique identifier
            example: 507f1f77bcf86cd799439011
          required: true
          name: id
          in: path
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UnpublishChangelogBody'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublishUnpublishSuccess'
        '400':
          description: |-
            Bad Request

            Possible error codes:
            - `invalid_id`: The changelog ID format is invalid
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - invalid_request_error
                        description: The type of error returned
                        example: invalid_request_error
                      code:
                        type: string
                        enum:
                          - invalid_id
                        description: Machine-readable error code
                        example: invalid_id
                      message:
                        type: string
                        description: Human-readable error message
                        example: An error occurred
                      param:
                        type: string
                        description: The parameter that caused the error (if applicable)
                        example: id
                      status:
                        type: number
                        enum:
                          - 400
                        description: HTTP status code
                        example: 400
                    required:
                      - type
                      - code
                      - message
                      - status
                required:
                  - error
        '404':
          description: |-
            Not Found

            Possible error codes:
            - `changelog_not_found`: No changelog exists with this ID
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - invalid_request_error
                        description: The type of error returned
                        example: invalid_request_error
                      code:
                        type: string
                        enum:
                          - changelog_not_found
                        description: Machine-readable error code
                        example: changelog_not_found
                      message:
                        type: string
                        description: Human-readable error message
                        example: An error occurred
                      param:
                        type: string
                        description: The parameter that caused the error (if applicable)
                        example: id
                      status:
                        type: number
                        enum:
                          - 404
                        description: HTTP status code
                        example: 404
                    required:
                      - type
                      - code
                      - message
                      - status
                required:
                  - error
  /v2/changelogs/subscribers:
    post:
      operationId: addChangelogSubscribers
      summary: Add changelog subscribers
      description: >-
        Adds email addresses as changelog subscribers in bulk.


        Subscribers will receive email notifications when new changelogs are
        published (if email notifications are enabled during publishing).


        ### Request Body


        - `emails` - Array of email addresses to add (required, 1-1000 emails)

        - `locale` - Locale for the subscribers (optional, defaults to
        organization default)


        ### Email Validation


        - Invalid email addresses are automatically filtered out

        - Emails are normalized (trimmed, lowercased)

        - Duplicate emails are deduplicated


        ### Rate Limiting


        This endpoint is rate limited to prevent abuse. If you need to import
        more subscribers, please contact support.


        ### Response


        Returns a confirmation with the count of processed emails:


        ```json

        {
          "object": "changelog_subscribers_import",
          "count": 150
        }

        ```


        ### Errors


        - `400` - Invalid request (empty emails array, too many emails)

        - `429` - Rate limit exceeded
      tags:
        - Changelogs
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/FeaturebaseVersion'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddChangelogSubscribersBody'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChangelogSubscribersImport'
        '400':
          description: |-
            Bad Request

            Possible error codes:
            - `invalid_request`: Empty emails array or too many emails
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - invalid_request_error
                        description: The type of error returned
                        example: invalid_request_error
                      code:
                        type: string
                        enum:
                          - invalid_request
                        description: Machine-readable error code
                        example: invalid_request
                      message:
                        type: string
                        description: Human-readable error message
                        example: An error occurred
                      param:
                        type: string
                        description: The parameter that caused the error (if applicable)
                        example: id
                      status:
                        type: number
                        enum:
                          - 400
                        description: HTTP status code
                        example: 400
                    required:
                      - type
                      - code
                      - message
                      - status
                required:
                  - error
    delete:
      operationId: removeChangelogSubscribers
      summary: Remove changelog subscribers
      description: >-
        Removes email addresses from changelog subscribers in bulk.


        Removed subscribers will no longer receive email notifications when new
        changelogs are published.


        ### Request Body


        - `emails` - Array of email addresses to remove (required, 1-1000
        emails)


        ### Email Handling


        - Emails that don't exist as subscribers are silently ignored

        - Emails are normalized (trimmed, lowercased) before matching


        ### Response


        Returns a confirmation with the count of processed emails:


        ```json

        {
          "object": "changelog_subscribers_removal",
          "count": 150
        }

        ```


        ### Errors


        - `400` - Invalid request (empty emails array, too many emails)
      tags:
        - Changelogs
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/FeaturebaseVersion'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RemoveChangelogSubscribersBody'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChangelogSubscribersRemoval'
        '400':
          description: |-
            Bad Request

            Possible error codes:
            - `invalid_request`: Empty emails array or too many emails
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - invalid_request_error
                        description: The type of error returned
                        example: invalid_request_error
                      code:
                        type: string
                        enum:
                          - invalid_request
                        description: Machine-readable error code
                        example: invalid_request
                      message:
                        type: string
                        description: Human-readable error message
                        example: An error occurred
                      param:
                        type: string
                        description: The parameter that caused the error (if applicable)
                        example: id
                      status:
                        type: number
                        enum:
                          - 400
                        description: HTTP status code
                        example: 400
                    required:
                      - type
                      - code
                      - message
                      - status
                required:
                  - error
  /v2/admins:
    get:
      operationId: listAdmins
      summary: List admins
      description: >-
        Returns all admins for your organization.


        This endpoint returns all admins at once (typically a small list). No
        pagination is supported.


        ### Response Format


        Returns a list object with:

        - `object` - Always "list"

        - `data` - Array of admin objects

        - `nextCursor` - Always null


        ### Admin Object


        Each admin includes:

        - `id` - Unique admin identifier

        - `name` - Admin's display name

        - `email` - Admin's email address

        - `picture` - Profile picture URL

        - `roleId` - ID of the role assigned to this admin
      tags:
        - Admins
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/FeaturebaseVersion'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdminList'
        '400':
          description: Bad Request - Validation error or invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
        '404':
          description: Not Found - Resource does not exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerError'
  /v2/admins/{id}:
    get:
      operationId: getAdmin
      summary: Get an admin by ID
      description: |-
        Retrieves a single admin by their unique identifier.

        Returns the admin object if found and they belong to your organization.

        ### Response

        Returns an admin object with:
        - `id` - Unique admin identifier
        - `name` - Admin's display name
        - `email` - Admin's email address
        - `picture` - Profile picture URL
        - `roleId` - ID of the role assigned to this admin

        ### Errors

        - `404` - Admin not found or doesn't belong to your organization
      tags:
        - Admins
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/FeaturebaseVersion'
        - schema:
            type: string
            description: Admin unique identifier
            example: 5fef50c5e9458a0012f82456
          required: true
          name: id
          in: path
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Admin'
        '400':
          description: |-
            Bad Request

            Possible error codes:
            - `invalid_id`: The admin ID format is invalid
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - invalid_request_error
                        description: The type of error returned
                        example: invalid_request_error
                      code:
                        type: string
                        enum:
                          - invalid_id
                        description: Machine-readable error code
                        example: invalid_id
                      message:
                        type: string
                        description: Human-readable error message
                        example: An error occurred
                      param:
                        type: string
                        description: The parameter that caused the error (if applicable)
                        example: id
                      status:
                        type: number
                        enum:
                          - 400
                        description: HTTP status code
                        example: 400
                    required:
                      - type
                      - code
                      - message
                      - status
                required:
                  - error
        '404':
          description: |-
            Not Found

            Possible error codes:
            - `admin_not_found`: No admin exists with this ID
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - invalid_request_error
                        description: The type of error returned
                        example: invalid_request_error
                      code:
                        type: string
                        enum:
                          - admin_not_found
                        description: Machine-readable error code
                        example: admin_not_found
                      message:
                        type: string
                        description: Human-readable error message
                        example: An error occurred
                      param:
                        type: string
                        description: The parameter that caused the error (if applicable)
                        example: id
                      status:
                        type: number
                        enum:
                          - 404
                        description: HTTP status code
                        example: 404
                    required:
                      - type
                      - code
                      - message
                      - status
                required:
                  - error
  /v2/admins/roles:
    get:
      operationId: listAdminRoles
      summary: List admin roles
      description: >-
        Returns all available admin roles and their permissions.


        This endpoint returns all roles at once (typically a small list). No
        pagination is supported.


        ### Response Format


        Returns a list object with:

        - `object` - Always "list"

        - `data` - Array of admin role objects

        - `nextCursor` - Always null


        ### Admin Role Object


        Each role includes:

        - `id` - Unique role identifier

        - `name` - Role name (e.g., "Admin", "Viewer")

        - `permissions` - Object containing permission flags


        ### Permissions


        The permissions object contains boolean flags for each permission:

        - `view_comments_private` - Can view private comments

        - `manage_comments` - Can manage comments

        - `manage_comments_private` - Can manage private comments

        - `set_comment_pinned` - Can pin comments

        - `moderate_comments` - Can moderate comments

        - `set_post_category` - Can change post categories

        - `set_post_pinned` - Can pin posts

        - `set_post_eta` - Can set post ETA

        - `set_post_tags` - Can manage post tags

        - `set_post_author` - Can change post author

        - `set_post_status` - Can change post status

        - `set_post_assignee` - Can assign posts

        - `set_post_custom_fields` - Can edit custom fields

        - `post_vote_on_behalf` - Can vote on behalf of users

        - `post_merge` - Can merge posts

        - `post_import` - Can import posts

        - `post_export` - Can export posts

        - `moderate_posts` - Can moderate posts

        - `view_users` - Can view users

        - `manage_users` - Can manage users

        - `view_posts_private` - Can view private posts

        - `view_private_post_tags` - Can view private tags

        - `manage_changelogs` - Can manage changelogs

        - `manage_surveys` - Can manage surveys

        - `manage_branding` - Can manage branding

        - `manage_billing` - Can manage billing

        - `manage_team_members` - Can manage team members

        - `manage_sso` - Can manage SSO settings

        - `manage_api` - Can manage API settings

        - `manage_statuses` - Can manage statuses

        - `manage_boards` - Can manage boards

        - `manage_post_tags` - Can manage post tags

        - `manage_custom_fields` - Can manage custom fields

        - `manage_moderation_settings` - Can manage moderation

        - `manage_roadmap` - Can manage roadmap

        - `manage_user_roles` - Can manage user roles

        - `manage_prioritization` - Can manage prioritization

        - `manage_notifications` - Can manage notifications

        - `manage_custom_domain` - Can manage custom domain

        - `manage_integrations` - Can manage integrations

        - `use_integrations` - Can use integrations

        - `manage_help_center` - Can manage help center

        - `auto_approve_posts` - Posts auto-approved
      tags:
        - Admins
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/FeaturebaseVersion'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdminRoleList'
        '400':
          description: Bad Request - Validation error or invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
        '404':
          description: Not Found - Resource does not exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerError'
  /v2/custom_fields:
    get:
      operationId: listCustomFields
      summary: List custom fields
      description: >-
        Returns all custom fields configured in your organization.


        This endpoint returns all custom fields at once (typically a small
        list). No pagination is supported.


        ### Response Format


        Returns a list object with:

        - `object` - Always "list"

        - `data` - Array of custom field objects

        - `nextCursor` - Always null


        ### Custom Field Object


        Each custom field includes:

        - `id` - Unique field identifier

        - `label` - Field label displayed to users

        - `type` - Field type (text, number, select, multi-select, checkbox,
        date)

        - `required` - Whether the field is required

        - `placeholder` - Placeholder text (for text/number fields)

        - `public` - Whether the field value is publicly visible

        - `internal` - Whether the field is for internal use only

        - `options` - Array of options (for select/multi-select fields)


        ### Field Types


        - `text` - Single line text input

        - `number` - Numeric input

        - `select` - Single-choice dropdown

        - `multi-select` - Multiple-choice dropdown

        - `checkbox` - Boolean checkbox

        - `date` - Date picker
      tags:
        - Custom Fields
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/FeaturebaseVersion'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomFieldList'
        '400':
          description: Bad Request - Validation error or invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
        '404':
          description: Not Found - Resource does not exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerError'
  /v2/custom_fields/{id}:
    get:
      operationId: getCustomField
      summary: Get a custom field by ID
      description: >-
        Retrieves a single custom field by its unique identifier.


        Returns the custom field object if found in your organization.


        ### Response


        Returns a custom field object with:

        - `id` - Unique field identifier

        - `label` - Field label displayed to users

        - `type` - Field type (text, number, select, multi-select, checkbox,
        date)

        - `required` - Whether the field is required

        - `placeholder` - Placeholder text (for text/number fields)

        - `public` - Whether the field value is publicly visible

        - `internal` - Whether the field is for internal use only

        - `options` - Array of options (for select/multi-select fields)


        ### Errors


        - `404` - Custom field not found in your organization
      tags:
        - Custom Fields
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/FeaturebaseVersion'
        - schema:
            type: string
            description: Custom field unique identifier
            example: 65d26304b2e65b1e1278170c
          required: true
          name: id
          in: path
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomField'
        '400':
          description: |-
            Bad Request

            Possible error codes:
            - `invalid_id`: The custom field ID format is invalid
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - invalid_request_error
                        description: The type of error returned
                        example: invalid_request_error
                      code:
                        type: string
                        enum:
                          - invalid_id
                        description: Machine-readable error code
                        example: invalid_id
                      message:
                        type: string
                        description: Human-readable error message
                        example: An error occurred
                      param:
                        type: string
                        description: The parameter that caused the error (if applicable)
                        example: id
                      status:
                        type: number
                        enum:
                          - 400
                        description: HTTP status code
                        example: 400
                    required:
                      - type
                      - code
                      - message
                      - status
                required:
                  - error
        '404':
          description: |-
            Not Found

            Possible error codes:
            - `custom_field_not_found`: No custom field exists with this ID
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - invalid_request_error
                        description: The type of error returned
                        example: invalid_request_error
                      code:
                        type: string
                        enum:
                          - custom_field_not_found
                        description: Machine-readable error code
                        example: custom_field_not_found
                      message:
                        type: string
                        description: Human-readable error message
                        example: An error occurred
                      param:
                        type: string
                        description: The parameter that caused the error (if applicable)
                        example: id
                      status:
                        type: number
                        enum:
                          - 404
                        description: HTTP status code
                        example: 404
                    required:
                      - type
                      - code
                      - message
                      - status
                required:
                  - error
  /v2/surveys:
    get:
      operationId: listSurveys
      summary: List surveys
      description: >-
        Returns all surveys configured in your Featurebase organization.


        ### Query Parameters


        - `limit` - Number of items to return (1-100, default 10)

        - `cursor` - Cursor for pagination

        - `type` - Filter by survey page type (text, link, rating,
        multiple-choice)

        - `isActive` - Filter by active status


        ### Response Format


        Returns a list object with:

        - `object` - Always "list"

        - `data` - Array of survey objects

        - `nextCursor` - Cursor for next page (null if no more results)


        ### Survey Object


        Each survey includes:

        - `id` - Unique identifier

        - `title` - Survey title

        - `description` - Survey description

        - `isActive` - Whether the survey is active

        - `responseCount` - Number of responses received

        - `targeting` - Targeting configuration (segments, URLs, CSS selectors)

        - `pages` - Array of survey pages/questions

        - `createdAt` - ISO 8601 timestamp when created

        - `updatedAt` - ISO 8601 timestamp when last updated
      tags:
        - Surveys
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/FeaturebaseVersion'
        - schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 10
            description: >-
              A limit on the number of objects to be returned, between 1 and
              100.
            example: 10
          required: false
          name: limit
          in: query
        - schema:
            type: string
            maxLength: 512
            description: >-
              An opaque cursor for pagination. Use the nextCursor value from a
              previous response to fetch the next page.
            example: eyJpZCI6IjY3NDM3NTJjYTgxYWU1OWQyNWNmODM0YiJ9
          required: false
          name: cursor
          in: query
        - schema:
            type: string
            enum:
              - text
              - link
              - rating
              - multiple-choice
            description: Filter by survey page type
            example: rating
          required: false
          name: type
          in: query
        - schema:
            type:
              - boolean
              - 'null'
            description: Filter by active status
            example: true
          required: false
          name: isActive
          in: query
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SurveyList'
        '400':
          description: |-
            Bad Request

            Possible error codes:
            - `invalid_cursor`: The pagination cursor is malformed or expired
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - invalid_request_error
                        description: The type of error returned
                        example: invalid_request_error
                      code:
                        type: string
                        enum:
                          - invalid_cursor
                        description: Machine-readable error code
                        example: invalid_cursor
                      message:
                        type: string
                        description: Human-readable error message
                        example: An error occurred
                      param:
                        type: string
                        description: The parameter that caused the error (if applicable)
                        example: id
                      status:
                        type: number
                        enum:
                          - 400
                        description: HTTP status code
                        example: 400
                    required:
                      - type
                      - code
                      - message
                      - status
                required:
                  - error
  /v2/surveys/{id}:
    get:
      operationId: getSurvey
      summary: Get a survey by ID
      description: |-
        Retrieves a single survey by its unique identifier.

        Returns the survey object if found in your organization.

        ### Response

        Returns a survey object with:
        - `id` - Unique identifier
        - `title` - Survey title
        - `description` - Survey description
        - `isActive` - Whether the survey is active
        - `responseCount` - Number of responses received
        - `targeting` - Targeting configuration
        - `pages` - Array of survey pages/questions
        - `createdAt` - ISO 8601 timestamp when created
        - `updatedAt` - ISO 8601 timestamp when last updated

        ### Survey Pages

        Each page represents a question or screen in the survey:
        - `type` - Page type (text, link, rating, multiple-choice)
        - `title` - Question title
        - `description` - Optional description
        - `logic` - Conditional logic rules
        - `defaultAction` - Default action when no logic matches

        ### Errors

        - `404` - Survey not found in your organization
      tags:
        - Surveys
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/FeaturebaseVersion'
        - schema:
            type: string
            description: Survey unique identifier
            example: 6743752ca81ae59d25cf834b
          required: true
          name: id
          in: path
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Survey'
        '400':
          description: |-
            Bad Request

            Possible error codes:
            - `invalid_id`: The survey ID format is invalid
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - invalid_request_error
                        description: The type of error returned
                        example: invalid_request_error
                      code:
                        type: string
                        enum:
                          - invalid_id
                        description: Machine-readable error code
                        example: invalid_id
                      message:
                        type: string
                        description: Human-readable error message
                        example: An error occurred
                      param:
                        type: string
                        description: The parameter that caused the error (if applicable)
                        example: id
                      status:
                        type: number
                        enum:
                          - 400
                        description: HTTP status code
                        example: 400
                    required:
                      - type
                      - code
                      - message
                      - status
                required:
                  - error
        '404':
          description: |-
            Not Found

            Possible error codes:
            - `survey_not_found`: No survey exists with this ID
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - invalid_request_error
                        description: The type of error returned
                        example: invalid_request_error
                      code:
                        type: string
                        enum:
                          - survey_not_found
                        description: Machine-readable error code
                        example: survey_not_found
                      message:
                        type: string
                        description: Human-readable error message
                        example: An error occurred
                      param:
                        type: string
                        description: The parameter that caused the error (if applicable)
                        example: id
                      status:
                        type: number
                        enum:
                          - 404
                        description: HTTP status code
                        example: 404
                    required:
                      - type
                      - code
                      - message
                      - status
                required:
                  - error
  /v2/surveys/{id}/responses:
    get:
      operationId: getSurveyResponses
      summary: Get survey responses
      description: |-
        Retrieves all user responses for a specific survey.

        ### Query Parameters

        - `pageId` - Filter responses to a specific survey page
        - `limit` - Number of items to return (1-100, default 10)
        - `cursor` - Cursor for pagination

        ### Response Format

        Returns a list object with:
        - `object` - Always "list"
        - `data` - Array of survey response objects
        - `nextCursor` - Cursor for next page (null if no more results)

        ### Survey Response Object

        Each response includes:
        - `id` - Unique response identifier
        - `user` - User who submitted the response (may be null for anonymous)
        - `responses` - Array of individual answers
        - `createdAt` - ISO 8601 timestamp when submitted

        ### Individual Response

        Each item in the responses array:
        - `pageId` - The survey page this response is for
        - `type` - Response type (text, rating, multiple-choice)
        - `value` - The response value

        ### Errors

        - `404` - Survey not found in your organization
      tags:
        - Surveys
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/FeaturebaseVersion'
        - schema:
            type: string
            description: Survey unique identifier
            example: 6743752ca81ae59d25cf834b
          required: true
          name: id
          in: path
        - schema:
            type: string
            description: Filter by survey page ID
            example: 6743752ca81ae59d25cf834c
          required: false
          name: pageId
          in: query
        - schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 10
            description: >-
              A limit on the number of objects to be returned, between 1 and
              100.
            example: 10
          required: false
          name: limit
          in: query
        - schema:
            type: string
            maxLength: 512
            description: >-
              An opaque cursor for pagination. Use the nextCursor value from a
              previous response to fetch the next page.
            example: eyJpZCI6IjY3MTJlMmQxNzU5MDRjZTI0YjJmOTYzNyJ9
          required: false
          name: cursor
          in: query
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SurveyResponseList'
        '400':
          description: |-
            Bad Request

            Possible error codes:
            - `invalid_id`: The survey ID format is invalid
            - `invalid_cursor`: The pagination cursor is malformed or expired
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - invalid_request_error
                        description: The type of error returned
                        example: invalid_request_error
                      code:
                        type: string
                        enum:
                          - invalid_id
                          - invalid_cursor
                        description: Machine-readable error code
                        example: invalid_id
                      message:
                        type: string
                        description: Human-readable error message
                        example: An error occurred
                      param:
                        type: string
                        description: The parameter that caused the error (if applicable)
                        example: id
                      status:
                        type: number
                        enum:
                          - 400
                        description: HTTP status code
                        example: 400
                    required:
                      - type
                      - code
                      - message
                      - status
                required:
                  - error
        '404':
          description: |-
            Not Found

            Possible error codes:
            - `survey_not_found`: No survey exists with this ID
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - invalid_request_error
                        description: The type of error returned
                        example: invalid_request_error
                      code:
                        type: string
                        enum:
                          - survey_not_found
                        description: Machine-readable error code
                        example: survey_not_found
                      message:
                        type: string
                        description: Human-readable error message
                        example: An error occurred
                      param:
                        type: string
                        description: The parameter that caused the error (if applicable)
                        example: id
                      status:
                        type: number
                        enum:
                          - 404
                        description: HTTP status code
                        example: 404
                    required:
                      - type
                      - code
                      - message
                      - status
                required:
                  - error
  /v2/help_center/help_centers:
    get:
      operationId: listHelpCenters
      summary: List help centers
      description: >-
        Returns all help centers configured in your Featurebase organization.


        Currently, Featurebase only supports one help center per organization,
        but we plan on supporting multiple help centers in the future.


        ### Query Parameters


        - `limit` - Number of items to return (1-100, default 10)

        - `cursor` - Cursor for pagination


        ### Response Format


        Returns a list object with:

        - `object` - Always "list"

        - `data` - Array of help center objects

        - `nextCursor` - Cursor for next page (null if no more results)


        ### Help Center Object


        Each help center includes:

        - `id` - Unique identifier

        - `displayName` - Help center display name

        - `title` - Help center title

        - `description` - Help center description

        - `isPublic` - Whether the help center is publicly accessible

        - `defaultLocale` - Default locale for content

        - `availableLocales` - Array of available locales

        - `navItems` - Navigation items configuration

        - `urls` - URL configuration (subpath, custom domain)

        - `createdAt` - ISO 8601 timestamp when created

        - `updatedAt` - ISO 8601 timestamp when last updated
      tags:
        - Help Centers
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/FeaturebaseVersion'
        - schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 10
            description: >-
              A limit on the number of objects to be returned, between 1 and
              100.
            example: 10
          required: false
          name: limit
          in: query
        - schema:
            type: string
            maxLength: 512
            description: >-
              An opaque cursor for pagination. Use the nextCursor value from a
              previous response to fetch the next page.
            example: eyJpZCI6IjJ0Z3kwaWc5ODJqNTRxZmwifQ
          required: false
          name: cursor
          in: query
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HelpCenterList'
        '400':
          description: |-
            Bad Request

            Possible error codes:
            - `invalid_cursor`: The pagination cursor is malformed or expired
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - invalid_request_error
                        description: The type of error returned
                        example: invalid_request_error
                      code:
                        type: string
                        enum:
                          - invalid_cursor
                        description: Machine-readable error code
                        example: invalid_cursor
                      message:
                        type: string
                        description: Human-readable error message
                        example: An error occurred
                      param:
                        type: string
                        description: The parameter that caused the error (if applicable)
                        example: id
                      status:
                        type: number
                        enum:
                          - 400
                        description: HTTP status code
                        example: 400
                    required:
                      - type
                      - code
                      - message
                      - status
                required:
                  - error
  /v2/help_center/help_centers/{id}:
    get:
      operationId: getHelpCenter
      summary: Get a help center by ID
      description: |-
        Retrieves a single help center by its unique identifier.

        Returns the help center object if found in your organization.

        ### Response

        Returns a help center object with:
        - `id` - Unique identifier
        - `displayName` - Help center display name
        - `title` - Help center title
        - `description` - Help center description
        - `searchPlaceholder` - Search input placeholder text
        - `isPublic` - Whether the help center is publicly accessible
        - `defaultLocale` - Default locale for content
        - `locale` - Current locale
        - `availableLocales` - Array of available locales
        - `navItems` - Navigation items configuration
        - `urls` - URL configuration (subpath, custom domain)
        - `createdAt` - ISO 8601 timestamp when created
        - `updatedAt` - ISO 8601 timestamp when last updated

        ### Errors

        - `404` - Help center not found in your organization
      tags:
        - Help Centers
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/FeaturebaseVersion'
        - schema:
            type: string
            minLength: 1
            maxLength: 16
            pattern: ^[a-zA-Z0-9]+$
            description: Help center unique identifier
            example: 2tgy0ig982j54qfl
          required: true
          name: id
          in: path
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HelpCenter'
        '400':
          description: |-
            Bad Request

            Possible error codes:
            - `invalid_id`: The help center ID format is invalid
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - invalid_request_error
                        description: The type of error returned
                        example: invalid_request_error
                      code:
                        type: string
                        enum:
                          - invalid_id
                        description: Machine-readable error code
                        example: invalid_id
                      message:
                        type: string
                        description: Human-readable error message
                        example: An error occurred
                      param:
                        type: string
                        description: The parameter that caused the error (if applicable)
                        example: id
                      status:
                        type: number
                        enum:
                          - 400
                        description: HTTP status code
                        example: 400
                    required:
                      - type
                      - code
                      - message
                      - status
                required:
                  - error
        '404':
          description: |-
            Not Found

            Possible error codes:
            - `help_center_not_found`: No help center exists with this ID
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - invalid_request_error
                        description: The type of error returned
                        example: invalid_request_error
                      code:
                        type: string
                        enum:
                          - help_center_not_found
                        description: Machine-readable error code
                        example: help_center_not_found
                      message:
                        type: string
                        description: Human-readable error message
                        example: An error occurred
                      param:
                        type: string
                        description: The parameter that caused the error (if applicable)
                        example: id
                      status:
                        type: number
                        enum:
                          - 404
                        description: HTTP status code
                        example: 404
                    required:
                      - type
                      - code
                      - message
                      - status
                required:
                  - error
  /v2/help_center/collections:
    get:
      operationId: listCollections
      summary: List collections
      description: >-
        Returns a paginated list of collections within your organization's help
        center.


        Collections are used to organize articles into logical groups.


        ### Query Parameters


        - `limit` - Number of items to return (1-100, default 10)

        - `cursor` - Cursor for pagination


        ### Response Format


        Returns a list object with:

        - `object` - Always "list"

        - `data` - Array of collection objects

        - `nextCursor` - Cursor for next page (null if no more results)


        ### Collection Object


        Each collection includes:

        - `id` - Unique identifier

        - `name` - Collection name

        - `description` - Collection description

        - `slug` - URL slug

        - `icon` - Collection icon (emoji or custom)

        - `parentId` - Parent collection ID (null for root collections)

        - `helpCenterId` - ID of the help center this collection belongs to

        - `organization` - Organization ID

        - `defaultLocale` - Default locale for content

        - `locale` - Current locale

        - `availableLocales` - Array of available locales

        - `featurebaseUrl` - Featurebase URL for the collection

        - `externalUrl` - External URL if custom domain is configured

        - `articleCount` - Number of articles in this collection

        - `authorCount` - Number of authors who contributed

        - `order` - Display order

        - `translations` - Translations for different locales

        - `createdAt` - ISO 8601 timestamp when created

        - `updatedAt` - ISO 8601 timestamp when last updated
      tags:
        - Help Centers
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/FeaturebaseVersion'
        - schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 10
            description: >-
              A limit on the number of objects to be returned, between 1 and
              100.
            example: 10
          required: false
          name: limit
          in: query
        - schema:
            type: string
            maxLength: 512
            description: >-
              An opaque cursor for pagination. Use the nextCursor value from a
              previous response to fetch the next page.
            example: eyJpZCI6IjY0NzQ2ODQifQ
          required: false
          name: cursor
          in: query
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CollectionList'
        '400':
          description: |-
            Bad Request

            Possible error codes:
            - `invalid_cursor`: The pagination cursor is malformed or expired
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - invalid_request_error
                        description: The type of error returned
                        example: invalid_request_error
                      code:
                        type: string
                        enum:
                          - invalid_cursor
                        description: Machine-readable error code
                        example: invalid_cursor
                      message:
                        type: string
                        description: Human-readable error message
                        example: An error occurred
                      param:
                        type: string
                        description: The parameter that caused the error (if applicable)
                        example: id
                      status:
                        type: number
                        enum:
                          - 400
                        description: HTTP status code
                        example: 400
                    required:
                      - type
                      - code
                      - message
                      - status
                required:
                  - error
    post:
      operationId: createCollection
      summary: Create a collection
      description: >-
        Creates a new collection in your organization's help center.


        ### Request Body


        Required attributes:

        - `name` - The name of the collection


        Optional attributes:

        - `description` - A description of the collection

        - `icon` - An icon object representing the collection icon (with type
        and value)

        - `parentId` - The ID of the parent collection, if any

        - `translations` - A dictionary of translations keyed by locale


        ### Response


        Returns the created collection object with:

        - `id` - Unique identifier

        - `name` - Collection name

        - `description` - Collection description

        - `slug` - URL slug

        - `icon` - Collection icon (emoji or custom)

        - `parentId` - Parent collection ID (null for root collections)

        - `helpCenterId` - ID of the help center this collection belongs to

        - `organization` - Organization ID

        - `defaultLocale` - Default locale for content

        - `locale` - Current locale

        - `availableLocales` - Array of available locales

        - `featurebaseUrl` - Featurebase URL for the collection

        - `externalUrl` - External URL if custom domain is configured

        - `articleCount` - Number of articles in this collection

        - `authorCount` - Number of authors who contributed

        - `order` - Display order

        - `translations` - Translations for different locales

        - `createdAt` - ISO 8601 timestamp when created

        - `updatedAt` - ISO 8601 timestamp when last updated
      tags:
        - Help Centers
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/FeaturebaseVersion'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCollectionBody_Nova'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Collection'
        '400':
          description: |-
            Bad Request

            Possible error codes:
            - `invalid_request`: Invalid collection data
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - invalid_request_error
                        description: The type of error returned
                        example: invalid_request_error
                      code:
                        type: string
                        enum:
                          - invalid_request
                        description: Machine-readable error code
                        example: invalid_request
                      message:
                        type: string
                        description: Human-readable error message
                        example: An error occurred
                      param:
                        type: string
                        description: The parameter that caused the error (if applicable)
                        example: id
                      status:
                        type: number
                        enum:
                          - 400
                        description: HTTP status code
                        example: 400
                    required:
                      - type
                      - code
                      - message
                      - status
                required:
                  - error
  /v2/help_center/collections/{id}:
    get:
      operationId: getCollection
      summary: Get a collection by ID
      description: >-
        Retrieves a specific collection by its unique identifier.


        Returns the collection object if found in your organization's help
        center.


        ### Response


        Returns a collection object with:

        - `id` - Unique identifier

        - `name` - Collection name

        - `description` - Collection description

        - `slug` - URL slug

        - `icon` - Collection icon (emoji or custom)

        - `parentId` - Parent collection ID (null for root collections)

        - `helpCenterId` - ID of the help center this collection belongs to

        - `organization` - Organization ID

        - `defaultLocale` - Default locale for content

        - `locale` - Current locale

        - `availableLocales` - Array of available locales

        - `featurebaseUrl` - Featurebase URL for the collection

        - `externalUrl` - External URL if custom domain is configured

        - `articleCount` - Number of articles in this collection

        - `authorCount` - Number of authors who contributed

        - `order` - Display order

        - `translations` - Translations for different locales

        - `createdAt` - ISO 8601 timestamp when created

        - `updatedAt` - ISO 8601 timestamp when last updated


        ### Errors


        - `404` - Collection not found in your organization's help center
      tags:
        - Help Centers
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/FeaturebaseVersion'
        - schema:
            type: string
            minLength: 1
            maxLength: 16
            pattern: ^[a-zA-Z0-9]+$
            description: Collection unique identifier
            example: '6474684'
          required: true
          name: id
          in: path
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Collection'
        '400':
          description: |-
            Bad Request

            Possible error codes:
            - `invalid_id`: The collection ID format is invalid
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - invalid_request_error
                        description: The type of error returned
                        example: invalid_request_error
                      code:
                        type: string
                        enum:
                          - invalid_id
                        description: Machine-readable error code
                        example: invalid_id
                      message:
                        type: string
                        description: Human-readable error message
                        example: An error occurred
                      param:
                        type: string
                        description: The parameter that caused the error (if applicable)
                        example: id
                      status:
                        type: number
                        enum:
                          - 400
                        description: HTTP status code
                        example: 400
                    required:
                      - type
                      - code
                      - message
                      - status
                required:
                  - error
        '404':
          description: |-
            Not Found

            Possible error codes:
            - `collection_not_found`: No collection exists with this ID
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - invalid_request_error
                        description: The type of error returned
                        example: invalid_request_error
                      code:
                        type: string
                        enum:
                          - collection_not_found
                        description: Machine-readable error code
                        example: collection_not_found
                      message:
                        type: string
                        description: Human-readable error message
                        example: An error occurred
                      param:
                        type: string
                        description: The parameter that caused the error (if applicable)
                        example: id
                      status:
                        type: number
                        enum:
                          - 404
                        description: HTTP status code
                        example: 404
                    required:
                      - type
                      - code
                      - message
                      - status
                required:
                  - error
    patch:
      operationId: updateCollection
      summary: Update a collection
      description: >-
        Updates an existing collection. Only include the fields you wish to
        update.


        ### Path Parameters


        - `id` - The unique identifier of the collection to update


        ### Request Body


        All fields are optional. Only provided fields will be updated:

        - `name` - The new name of the collection

        - `description` - The new description of the collection

        - `icon` - An updated icon object for the collection (with type and
        value)

        - `parentId` - The new parent collection ID, if applicable (null for
        root level)

        - `translations` - A dictionary of updated translations keyed by locale
        code


        ### Response


        Returns the updated collection object with:

        - `id` - Unique identifier

        - `name` - Collection name

        - `description` - Collection description

        - `slug` - URL slug

        - `icon` - Collection icon (emoji or custom)

        - `parentId` - Parent collection ID (null for root collections)

        - `helpCenterId` - ID of the help center this collection belongs to

        - `organization` - Organization ID

        - `defaultLocale` - Default locale for content

        - `locale` - Current locale

        - `availableLocales` - Array of available locales

        - `featurebaseUrl` - Featurebase URL for the collection

        - `externalUrl` - External URL if custom domain is configured

        - `articleCount` - Number of articles in this collection

        - `authorCount` - Number of authors who contributed

        - `order` - Display order

        - `translations` - Translations for different locales

        - `createdAt` - ISO 8601 timestamp when created

        - `updatedAt` - ISO 8601 timestamp when last updated


        ### Errors


        - `404` - Collection not found in your organization's help center
      tags:
        - Help Centers
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/FeaturebaseVersion'
        - schema:
            type: string
            minLength: 1
            maxLength: 16
            pattern: ^[a-zA-Z0-9]+$
            description: The collection unique identifier
            example: '3416135'
          required: true
          name: id
          in: path
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateCollectionBody_Nova'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Collection'
        '400':
          description: |-
            Bad Request

            Possible error codes:
            - `invalid_id`: The collection ID format is invalid
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - invalid_request_error
                        description: The type of error returned
                        example: invalid_request_error
                      code:
                        type: string
                        enum:
                          - invalid_id
                        description: Machine-readable error code
                        example: invalid_id
                      message:
                        type: string
                        description: Human-readable error message
                        example: An error occurred
                      param:
                        type: string
                        description: The parameter that caused the error (if applicable)
                        example: id
                      status:
                        type: number
                        enum:
                          - 400
                        description: HTTP status code
                        example: 400
                    required:
                      - type
                      - code
                      - message
                      - status
                required:
                  - error
        '404':
          description: |-
            Not Found

            Possible error codes:
            - `collection_not_found`: No collection exists with this ID
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - invalid_request_error
                        description: The type of error returned
                        example: invalid_request_error
                      code:
                        type: string
                        enum:
                          - collection_not_found
                        description: Machine-readable error code
                        example: collection_not_found
                      message:
                        type: string
                        description: Human-readable error message
                        example: An error occurred
                      param:
                        type: string
                        description: The parameter that caused the error (if applicable)
                        example: id
                      status:
                        type: number
                        enum:
                          - 404
                        description: HTTP status code
                        example: 404
                    required:
                      - type
                      - code
                      - message
                      - status
                required:
                  - error
    delete:
      operationId: deleteCollection
      summary: Delete a collection
      description: |-
        Deletes an existing collection.

        ### Path Parameters

        - `id` - The unique identifier of the collection to delete

        ### Response

        Returns a deletion confirmation object:
        - `id` - The ID of the deleted collection
        - `object` - Always "collection"
        - `deleted` - Always true

        ### Errors

        - `404` - Collection not found in your organization's help center
      tags:
        - Help Centers
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/FeaturebaseVersion'
        - schema:
            type: string
            minLength: 1
            maxLength: 16
            pattern: ^[a-zA-Z0-9]+$
            description: The collection unique identifier
            example: '3416135'
          required: true
          name: id
          in: path
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeletedCollection'
        '400':
          description: |-
            Bad Request

            Possible error codes:
            - `invalid_id`: The collection ID format is invalid
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - invalid_request_error
                        description: The type of error returned
                        example: invalid_request_error
                      code:
                        type: string
                        enum:
                          - invalid_id
                        description: Machine-readable error code
                        example: invalid_id
                      message:
                        type: string
                        description: Human-readable error message
                        example: An error occurred
                      param:
                        type: string
                        description: The parameter that caused the error (if applicable)
                        example: id
                      status:
                        type: number
                        enum:
                          - 400
                        description: HTTP status code
                        example: 400
                    required:
                      - type
                      - code
                      - message
                      - status
                required:
                  - error
        '404':
          description: |-
            Not Found

            Possible error codes:
            - `collection_not_found`: No collection exists with this ID
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - invalid_request_error
                        description: The type of error returned
                        example: invalid_request_error
                      code:
                        type: string
                        enum:
                          - collection_not_found
                        description: Machine-readable error code
                        example: collection_not_found
                      message:
                        type: string
                        description: Human-readable error message
                        example: An error occurred
                      param:
                        type: string
                        description: The parameter that caused the error (if applicable)
                        example: id
                      status:
                        type: number
                        enum:
                          - 404
                        description: HTTP status code
                        example: 404
                    required:
                      - type
                      - code
                      - message
                      - status
                required:
                  - error
  /v2/help_center/articles:
    get:
      operationId: listArticles
      summary: List articles
      description: >-
        Returns a paginated list of articles within your organization's help
        center.


        Articles are the main content pieces that contain documentation, guides,
        and FAQs.


        ### Query Parameters


        - `limit` - Number of items to return (1-100, default 10)

        - `cursor` - Cursor for pagination

        - `state` - Filter by article state: "live", "draft", or "all" (default
        "live")

        - `parentId` - Filter by parent collection ID


        ### Response Format


        Returns a list object with:

        - `object` - Always "list"

        - `data` - Array of article objects

        - `nextCursor` - Cursor for next page (null if no more results)


        ### Article Object


        Each article includes:

        - `id` - Unique identifier

        - `title` - Article title

        - `description` - Article description

        - `body` - Article content (HTML)

        - `slug` - URL slug

        - `icon` - Article icon (emoji or custom)

        - `parentId` - Parent collection ID

        - `helpCenterId` - ID of the help center this article belongs to

        - `organization` - Organization ID

        - `state` - Article state (live or draft)

        - `defaultLocale` - Default locale for content

        - `locale` - Current locale

        - `availableLocales` - Array of available locales

        - `publishedLocales` - Array of locales where article is published

        - `featurebaseUrl` - Featurebase URL for the article

        - `externalUrl` - External URL if custom domain is configured

        - `author` - Author information (name, authorId, avatarUrl)

        - `order` - Display order

        - `isPublished` - Whether the article is published

        - `isDraftDiffersFromLive` - Whether draft differs from live version

        - `translations` - Translations for different locales

        - `createdAt` - ISO 8601 timestamp when created

        - `updatedAt` - ISO 8601 timestamp when last updated

        - `liveUpdatedAt` - ISO 8601 timestamp when live version was last
        updated
      tags:
        - Help Centers
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/FeaturebaseVersion'
        - schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 10
            description: >-
              A limit on the number of objects to be returned, between 1 and
              100.
            example: 10
          required: false
          name: limit
          in: query
        - schema:
            type: string
            maxLength: 512
            description: >-
              An opaque cursor for pagination. Use the nextCursor value from a
              previous response to fetch the next page of results.
            example: eyJpZCI6IjUwN2YxZjc3YmNmODZjZDc5OTQzOTAxMSJ9
          required: false
          name: cursor
          in: query
        - schema:
            type: string
            enum:
              - live
              - draft
              - all
            default: live
            description: >-
              Filter articles by state. Use "all" to get both draft and live
              articles.
            example: live
          required: false
          name: state
          in: query
        - schema:
            type: string
            minLength: 1
            maxLength: 16
            pattern: ^[a-zA-Z0-9]+$
            description: Filter articles by parent collection ID
            example: '6474684'
          required: false
          name: parentId
          in: query
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArticleList'
        '400':
          description: |-
            Bad Request

            Possible error codes:
            - `invalid_cursor`: The pagination cursor is malformed or expired
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - invalid_request_error
                        description: The type of error returned
                        example: invalid_request_error
                      code:
                        type: string
                        enum:
                          - invalid_cursor
                        description: Machine-readable error code
                        example: invalid_cursor
                      message:
                        type: string
                        description: Human-readable error message
                        example: An error occurred
                      param:
                        type: string
                        description: The parameter that caused the error (if applicable)
                        example: id
                      status:
                        type: number
                        enum:
                          - 400
                        description: HTTP status code
                        example: 400
                    required:
                      - type
                      - code
                      - message
                      - status
                required:
                  - error
    post:
      operationId: createArticle
      summary: Create an article
      description: >-
        Creates a new article in your organization's help center.


        ### Request Body


        Required attributes:

        - `title` - The title of the article


        Optional attributes:

        - `description` - A brief description of the article

        - `body` - The HTML content of the article (supports external image URLs
        and base64 data URIs)

        - `formatter` - Content formatter: "default" or "ai" (AI converts
        markdown/html to Featurebase format)

        - `parentId` - The ID of the parent collection

        - `icon` - Icon object with type and value

        - `state` - "live" or "draft" (defaults to "draft")

        - `translations` - Dictionary of translations keyed by locale


        ### Response


        Returns the created article object with:

        - `id` - Unique identifier

        - `title` - Article title

        - `description` - Article description

        - `body` - Article content (HTML)

        - `slug` - URL slug

        - `icon` - Article icon (emoji or custom)

        - `parentId` - Parent collection ID

        - `helpCenterId` - ID of the help center this article belongs to

        - `organization` - Organization ID

        - `state` - Article state (live or draft)

        - `author` - Author information (name, authorId, avatarUrl)

        - `translations` - Translations for different locales

        - `createdAt` - ISO 8601 timestamp when created

        - `updatedAt` - ISO 8601 timestamp when last updated
      tags:
        - Help Centers
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/FeaturebaseVersion'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateArticleBody_Nova'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Article'
        '400':
          description: |-
            Bad Request

            Possible error codes:
            - `invalid_request`: Invalid article data
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - invalid_request_error
                        description: The type of error returned
                        example: invalid_request_error
                      code:
                        type: string
                        enum:
                          - invalid_request
                        description: Machine-readable error code
                        example: invalid_request
                      message:
                        type: string
                        description: Human-readable error message
                        example: An error occurred
                      param:
                        type: string
                        description: The parameter that caused the error (if applicable)
                        example: id
                      status:
                        type: number
                        enum:
                          - 400
                        description: HTTP status code
                        example: 400
                    required:
                      - type
                      - code
                      - message
                      - status
                required:
                  - error
  /v2/help_center/articles/{id}:
    get:
      operationId: getArticle
      summary: Get an article by ID
      description: >-
        Retrieves a specific article by its unique identifier.


        Returns the article object if found in your organization's help center.


        ### Query Parameters


        - `state` - Article state to retrieve: "live" or "draft" (default
        "live")


        ### Response


        Returns an article object with:

        - `id` - Unique identifier

        - `title` - Article title

        - `description` - Article description

        - `body` - Article content (HTML)

        - `slug` - URL slug

        - `icon` - Article icon (emoji or custom)

        - `parentId` - Parent collection ID

        - `helpCenterId` - ID of the help center this article belongs to

        - `organization` - Organization ID

        - `state` - Article state (live or draft)

        - `defaultLocale` - Default locale for content

        - `locale` - Current locale

        - `availableLocales` - Array of available locales

        - `publishedLocales` - Array of locales where article is published

        - `featurebaseUrl` - Featurebase URL for the article

        - `externalUrl` - External URL if custom domain is configured

        - `author` - Author information (name, authorId, avatarUrl)

        - `order` - Display order

        - `isPublished` - Whether the article is published

        - `isDraftDiffersFromLive` - Whether draft differs from live version

        - `translations` - Translations for different locales

        - `createdAt` - ISO 8601 timestamp when created

        - `updatedAt` - ISO 8601 timestamp when last updated

        - `liveUpdatedAt` - ISO 8601 timestamp when live version was last
        updated


        ### Errors


        - `404` - Article not found in your organization's help center
      tags:
        - Help Centers
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/FeaturebaseVersion'
        - schema:
            type: string
            minLength: 1
            maxLength: 16
            pattern: ^[a-zA-Z0-9]+$
            description: Article unique identifier
            example: '1234567'
          required: true
          name: id
          in: path
        - schema:
            type: string
            enum:
              - live
              - draft
            default: live
            description: Article state to retrieve
            example: live
          required: false
          name: state
          in: query
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Article'
        '400':
          description: |-
            Bad Request

            Possible error codes:
            - `invalid_id`: The article ID format is invalid
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - invalid_request_error
                        description: The type of error returned
                        example: invalid_request_error
                      code:
                        type: string
                        enum:
                          - invalid_id
                        description: Machine-readable error code
                        example: invalid_id
                      message:
                        type: string
                        description: Human-readable error message
                        example: An error occurred
                      param:
                        type: string
                        description: The parameter that caused the error (if applicable)
                        example: id
                      status:
                        type: number
                        enum:
                          - 400
                        description: HTTP status code
                        example: 400
                    required:
                      - type
                      - code
                      - message
                      - status
                required:
                  - error
        '404':
          description: |-
            Not Found

            Possible error codes:
            - `article_not_found`: No article exists with this ID
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - invalid_request_error
                        description: The type of error returned
                        example: invalid_request_error
                      code:
                        type: string
                        enum:
                          - article_not_found
                        description: Machine-readable error code
                        example: article_not_found
                      message:
                        type: string
                        description: Human-readable error message
                        example: An error occurred
                      param:
                        type: string
                        description: The parameter that caused the error (if applicable)
                        example: id
                      status:
                        type: number
                        enum:
                          - 404
                        description: HTTP status code
                        example: 404
                    required:
                      - type
                      - code
                      - message
                      - status
                required:
                  - error
    patch:
      operationId: updateArticle
      summary: Update an article
      description: >-
        Updates an existing article. Only include the fields you wish to update.


        ### Path Parameters


        - `id` - The unique identifier of the article to update


        ### Request Body


        All fields are optional. Only provided fields will be updated:

        - `title` - The new title of the article

        - `description` - The new description of the article

        - `body` - The new HTML content of the article

        - `formatter` - Content formatter: "default" or "ai"

        - `icon` - Updated icon object for the article

        - `parentId` - New parent collection ID

        - `authorId` - ID of the new author (must be a member of the
        organization)

        - `state` - "live" or "draft" - if "live", publishes immediately

        - `translations` - Dictionary of updated translations keyed by locale


        ### Response


        Returns the updated article object with:

        - `id` - Unique identifier

        - `title` - Article title

        - `description` - Article description

        - `body` - Article content (HTML)

        - `slug` - URL slug

        - `icon` - Article icon (emoji or custom)

        - `parentId` - Parent collection ID

        - `helpCenterId` - ID of the help center this article belongs to

        - `organization` - Organization ID

        - `state` - Article state (live or draft)

        - `author` - Author information (name, authorId, avatarUrl)

        - `translations` - Translations for different locales

        - `createdAt` - ISO 8601 timestamp when created

        - `updatedAt` - ISO 8601 timestamp when last updated


        ### Errors


        - `404` - Article not found in your organization's help center
      tags:
        - Help Centers
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/FeaturebaseVersion'
        - schema:
            type: string
            minLength: 1
            maxLength: 16
            pattern: ^[a-zA-Z0-9]+$
            description: The article unique identifier
            example: '1234567'
          required: true
          name: id
          in: path
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateArticleBody_Nova'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Article'
        '400':
          description: |-
            Bad Request

            Possible error codes:
            - `invalid_id`: The article ID format is invalid
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - invalid_request_error
                        description: The type of error returned
                        example: invalid_request_error
                      code:
                        type: string
                        enum:
                          - invalid_id
                        description: Machine-readable error code
                        example: invalid_id
                      message:
                        type: string
                        description: Human-readable error message
                        example: An error occurred
                      param:
                        type: string
                        description: The parameter that caused the error (if applicable)
                        example: id
                      status:
                        type: number
                        enum:
                          - 400
                        description: HTTP status code
                        example: 400
                    required:
                      - type
                      - code
                      - message
                      - status
                required:
                  - error
        '404':
          description: |-
            Not Found

            Possible error codes:
            - `article_not_found`: No article exists with this ID
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - invalid_request_error
                        description: The type of error returned
                        example: invalid_request_error
                      code:
                        type: string
                        enum:
                          - article_not_found
                        description: Machine-readable error code
                        example: article_not_found
                      message:
                        type: string
                        description: Human-readable error message
                        example: An error occurred
                      param:
                        type: string
                        description: The parameter that caused the error (if applicable)
                        example: id
                      status:
                        type: number
                        enum:
                          - 404
                        description: HTTP status code
                        example: 404
                    required:
                      - type
                      - code
                      - message
                      - status
                required:
                  - error
    delete:
      operationId: deleteArticle
      summary: Delete an article
      description: |-
        Deletes an existing article.

        ### Path Parameters

        - `id` - The unique identifier of the article to delete

        ### Response

        Returns a deletion confirmation object:
        - `id` - The ID of the deleted article
        - `object` - Always "article"
        - `deleted` - Always true

        ### Errors

        - `404` - Article not found in your organization's help center
      tags:
        - Help Centers
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/FeaturebaseVersion'
        - schema:
            type: string
            minLength: 1
            maxLength: 16
            pattern: ^[a-zA-Z0-9]+$
            description: The article unique identifier
            example: '1234567'
          required: true
          name: id
          in: path
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeletedArticle'
        '400':
          description: |-
            Bad Request

            Possible error codes:
            - `invalid_id`: The article ID format is invalid
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - invalid_request_error
                        description: The type of error returned
                        example: invalid_request_error
                      code:
                        type: string
                        enum:
                          - invalid_id
                        description: Machine-readable error code
                        example: invalid_id
                      message:
                        type: string
                        description: Human-readable error message
                        example: An error occurred
                      param:
                        type: string
                        description: The parameter that caused the error (if applicable)
                        example: id
                      status:
                        type: number
                        enum:
                          - 400
                        description: HTTP status code
                        example: 400
                    required:
                      - type
                      - code
                      - message
                      - status
                required:
                  - error
        '404':
          description: |-
            Not Found

            Possible error codes:
            - `article_not_found`: No article exists with this ID
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - invalid_request_error
                        description: The type of error returned
                        example: invalid_request_error
                      code:
                        type: string
                        enum:
                          - article_not_found
                        description: Machine-readable error code
                        example: article_not_found
                      message:
                        type: string
                        description: Human-readable error message
                        example: An error occurred
                      param:
                        type: string
                        description: The parameter that caused the error (if applicable)
                        example: id
                      status:
                        type: number
                        enum:
                          - 404
                        description: HTTP status code
                        example: 404
                    required:
                      - type
                      - code
                      - message
                      - status
                required:
                  - error
  /v2/contacts:
    get:
      operationId: listContacts
      summary: List contacts
      description: >-
        Returns a list of contacts (customers and leads) in your organization
        using cursor-based pagination.


        ### Query Parameters


        - `limit` - Number of contacts to return (1-100, default 10)

        - `cursor` - Cursor from previous response for pagination

        - `contactType` - Filter by contact type: "customer" (default), "lead",
        or "all"


        ### Response Format


        Returns a list object with:

        - `object` - Always "list"

        - `data` - Array of contact objects

        - `nextCursor` - Cursor for the next page, or null if no more results


        ### Contact Object


        Each contact includes:

        - `id` - Unique contact identifier

        - `userId` - External user ID from SSO (if set)

        - `email` - Contact email address

        - `name` - Contact display name

        - `profilePicture` - Profile picture URL

        - `type` - Contact type ("customer" or "lead")

        - `companies` - Array of companies the contact belongs to

        - `customFields` - Custom field values

        - `postsCreated` - Number of posts created

        - `commentsCreated` - Number of comments created

        - `lastActivity` - Last activity timestamp


        ### Example


        ```json

        {
          "object": "list",
          "data": [
            {
              "object": "contact",
              "id": "676f0f6765bdaa7d7d760f88",
              "email": "john@example.com",
              "name": "John Doe",
              "type": "customer",
              ...
            }
          ],
          "nextCursor": "eyJpZCI6IjUwN2YxZjc3YmNmODZjZDc5OTQzOTAxMSJ9"
        }

        ```


        ### Version Availability


        This endpoint is only available in API version 2026-01-01.nova and
        newer.
      tags:
        - Contacts
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/FeaturebaseVersion'
        - schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 10
            description: >-
              A limit on the number of objects to be returned, between 1 and
              100.
            example: 10
          required: false
          name: limit
          in: query
        - schema:
            type: string
            maxLength: 512
            description: >-
              An opaque cursor for pagination. Use the nextCursor value from a
              previous response to fetch the next page of results.
            example: eyJpZCI6IjUwN2YxZjc3YmNmODZjZDc5OTQzOTAxMSJ9
          required: false
          name: cursor
          in: query
        - schema:
            type: string
            enum:
              - customer
              - lead
              - all
            default: customer
            description: Filter contacts by type. Defaults to "customer".
            example: customer
          required: false
          name: contactType
          in: query
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContactList'
        '400':
          description: |-
            Bad Request

            Possible error codes:
            - `invalid_cursor`: The pagination cursor is malformed or expired
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - invalid_request_error
                        description: The type of error returned
                        example: invalid_request_error
                      code:
                        type: string
                        enum:
                          - invalid_cursor
                        description: Machine-readable error code
                        example: invalid_cursor
                      message:
                        type: string
                        description: Human-readable error message
                        example: An error occurred
                      param:
                        type: string
                        description: The parameter that caused the error (if applicable)
                        example: id
                      status:
                        type: number
                        enum:
                          - 400
                        description: HTTP status code
                        example: 400
                    required:
                      - type
                      - code
                      - message
                      - status
                required:
                  - error
    post:
      operationId: upsertContact
      summary: Create or update a contact
      description: >-
        Creates a new contact or updates an existing one.


        If a contact with the given `email` or `userId` already exists, it will
        be updated.

        Otherwise, a new contact will be created.


        **At least one of `email` or `userId` must be provided for
        identification.**


        ### Request Body


        | Field | Type | Required | Description |

        |-------|------|----------|-------------|

        | `email` | string | One of email/userId | Contact email address |

        | `userId` | string | One of email/userId | External user ID from your
        system |

        | `name` | string | No | Contact display name |

        | `profilePicture` | string | No | Profile picture URL |

        | `companies` | array | No | Companies the contact belongs to |

        | `customFields` | object | No | Custom field values |

        | `subscribedToChangelog` | boolean | No | Whether subscribed to
        changelog |

        | `locale` | string | No | Contact locale/language |

        | `phone` | string | No | Contact phone number |

        | `roles` | array | No | Role IDs to assign |

        | `userHash` | string | No | HMAC hash for identity verification |

        | `createdAt` | string | No | When the contact was created (ISO 8601) |


        ### Company Object


        Each company in the `companies` array can have:

        - `id` (required) - External company ID from your system

        - `name` (required) - Company name

        - `monthlySpend` - Monthly spend/revenue

        - `customFields` - Custom field values

        - `industry` - Industry

        - `website` - Company website URL

        - `plan` - Current plan/subscription

        - `companySize` - Number of employees

        - `createdAt` - When the company was created


        ### Response


        Returns the created or updated contact object.


        - **201 Created** - A new contact was created

        - **200 OK** - An existing contact was updated


        ### Example Request


        ```json

        {
          "email": "john@example.com",
          "name": "John Doe",
          "userId": "usr_12345",
          "companies": [
            {
              "id": "company_123",
              "name": "Acme Inc",
              "monthlySpend": 500,
              "plan": "enterprise"
            }
          ],
          "customFields": {
            "plan": "pro",
            "signupSource": "website"
          },
          "subscribedToChangelog": true
        }

        ```


        ### Example Response


        ```json

        {
          "object": "contact",
          "id": "676f0f6765bdaa7d7d760f88",
          "email": "john@example.com",
          "name": "John Doe",
          "userId": "usr_12345",
          "type": "customer",
          "companies": [...],
          "customFields": {...},
          ...
        }

        ```


        ### Version Availability


        This endpoint is only available in API version 2026-01-01.nova and
        newer.
      tags:
        - Contacts
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/FeaturebaseVersion'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpsertContactBody'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Contact'
                  - type: object
        '400':
          description: |-
            Bad Request

            Possible error codes:
            - `missing_parameter`: Either email or userId must be provided
            - `invalid_request`: Invalid contact identification parameters
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - invalid_request_error
                        description: The type of error returned
                        example: invalid_request_error
                      code:
                        type: string
                        enum:
                          - missing_parameter
                          - invalid_request
                        description: Machine-readable error code
                        example: missing_parameter
                      message:
                        type: string
                        description: Human-readable error message
                        example: An error occurred
                      param:
                        type: string
                        description: The parameter that caused the error (if applicable)
                        example: id
                      status:
                        type: number
                        enum:
                          - 400
                        description: HTTP status code
                        example: 400
                    required:
                      - type
                      - code
                      - message
                      - status
                required:
                  - error
  /v2/contacts/{id}:
    get:
      operationId: getContactById
      summary: Get contact by ID
      description: >-
        Retrieves a single contact by their Featurebase ID.


        Returns both customers and leads.


        ### Path Parameters


        - `id` - The Featurebase contact ID (24-character ObjectId)


        ### Response Format


        Returns a single contact object with:

        - `object` - Always "contact"

        - `id` - Unique contact identifier

        - `userId` - External user ID from SSO (if set)

        - `email` - Contact email address

        - `name` - Contact display name

        - `profilePicture` - Profile picture URL

        - `type` - Contact type ("customer" or "lead")

        - `companies` - Array of companies the contact belongs to

        - `customFields` - Custom field values

        - `postsCreated` - Number of posts created

        - `commentsCreated` - Number of comments created

        - `lastActivity` - Last activity timestamp


        ### Example


        ```json

        {
          "object": "contact",
          "id": "676f0f6765bdaa7d7d760f88",
          "email": "john@example.com",
          "name": "John Doe",
          "type": "customer",
          ...
        }

        ```


        ### Version Availability


        This endpoint is only available in API version 2026-01-01.nova and
        newer.
      tags:
        - Contacts
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/FeaturebaseVersion'
        - schema:
            type: string
            description: Featurebase contact ID
            example: 507f1f77bcf86cd799439011
          required: true
          name: id
          in: path
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Contact'
                  - type: object
        '400':
          description: |-
            Bad Request

            Possible error codes:
            - `invalid_id`: The contact ID format is invalid
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - invalid_request_error
                        description: The type of error returned
                        example: invalid_request_error
                      code:
                        type: string
                        enum:
                          - invalid_id
                        description: Machine-readable error code
                        example: invalid_id
                      message:
                        type: string
                        description: Human-readable error message
                        example: An error occurred
                      param:
                        type: string
                        description: The parameter that caused the error (if applicable)
                        example: id
                      status:
                        type: number
                        enum:
                          - 400
                        description: HTTP status code
                        example: 400
                    required:
                      - type
                      - code
                      - message
                      - status
                required:
                  - error
        '404':
          description: |-
            Not Found

            Possible error codes:
            - `contact_not_found`: No contact exists with this ID
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - invalid_request_error
                        description: The type of error returned
                        example: invalid_request_error
                      code:
                        type: string
                        enum:
                          - contact_not_found
                        description: Machine-readable error code
                        example: contact_not_found
                      message:
                        type: string
                        description: Human-readable error message
                        example: An error occurred
                      param:
                        type: string
                        description: The parameter that caused the error (if applicable)
                        example: id
                      status:
                        type: number
                        enum:
                          - 404
                        description: HTTP status code
                        example: 404
                    required:
                      - type
                      - code
                      - message
                      - status
                required:
                  - error
    delete:
      operationId: deleteContactById
      summary: Delete contact by ID
      description: >-
        Permanently deletes a contact by their Featurebase ID.


        Supports deleting both customers and leads.


        ### Path Parameters


        - `id` - The Featurebase contact ID (24-character ObjectId)


        ### Deletion Behavior


        When a contact is deleted:

        - The contact record is permanently removed

        - Associated data cleanup is triggered asynchronously

        - Comments and posts created by the contact are handled according to
        retention policies


        ### Response


        Returns a deletion confirmation object:

        - `id` - The ID of the deleted contact

        - `object` - Always "contact"

        - `deleted` - Always `true`


        ### Example Response


        ```json

        {
          "id": "676f0f6765bdaa7d7d760f88",
          "object": "contact",
          "deleted": true
        }

        ```


        ### Version Availability


        This endpoint is only available in API version 2026-01-01.nova and
        newer.
      tags:
        - Contacts
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/FeaturebaseVersion'
        - schema:
            type: string
            description: Featurebase contact ID
            example: 507f1f77bcf86cd799439011
          required: true
          name: id
          in: path
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeletedContact'
        '400':
          description: |-
            Bad Request

            Possible error codes:
            - `invalid_id`: The contact ID format is invalid
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - invalid_request_error
                        description: The type of error returned
                        example: invalid_request_error
                      code:
                        type: string
                        enum:
                          - invalid_id
                        description: Machine-readable error code
                        example: invalid_id
                      message:
                        type: string
                        description: Human-readable error message
                        example: An error occurred
                      param:
                        type: string
                        description: The parameter that caused the error (if applicable)
                        example: id
                      status:
                        type: number
                        enum:
                          - 400
                        description: HTTP status code
                        example: 400
                    required:
                      - type
                      - code
                      - message
                      - status
                required:
                  - error
        '404':
          description: |-
            Not Found

            Possible error codes:
            - `contact_not_found`: No contact exists with this ID
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - invalid_request_error
                        description: The type of error returned
                        example: invalid_request_error
                      code:
                        type: string
                        enum:
                          - contact_not_found
                        description: Machine-readable error code
                        example: contact_not_found
                      message:
                        type: string
                        description: Human-readable error message
                        example: An error occurred
                      param:
                        type: string
                        description: The parameter that caused the error (if applicable)
                        example: id
                      status:
                        type: number
                        enum:
                          - 404
                        description: HTTP status code
                        example: 404
                    required:
                      - type
                      - code
                      - message
                      - status
                required:
                  - error
  /v2/contacts/by-user-id/{userId}:
    get:
      operationId: getContactByUserId
      summary: Get contact by external user ID
      description: >-
        Retrieves a single contact by their external user ID (from your system
        via SSO).


        **Important:** This endpoint only returns customers (type: "customer").
        Leads are not returned.


        ### Path Parameters


        - `userId` - The external user ID from your system (matched via SSO
        integration)


        ### Response Format


        Returns a single contact object with:

        - `object` - Always "contact"

        - `id` - Unique contact identifier

        - `userId` - External user ID from SSO

        - `email` - Contact email address

        - `name` - Contact display name

        - `profilePicture` - Profile picture URL

        - `type` - Always "customer" for this endpoint

        - `companies` - Array of companies the contact belongs to

        - `customFields` - Custom field values

        - `postsCreated` - Number of posts created

        - `commentsCreated` - Number of comments created

        - `lastActivity` - Last activity timestamp


        ### Example


        ```json

        {
          "object": "contact",
          "id": "676f0f6765bdaa7d7d760f88",
          "userId": "usr_12345",
          "email": "john@example.com",
          "name": "John Doe",
          "type": "customer",
          ...
        }

        ```


        ### Use Case


        This endpoint is useful when you need to look up a contact using your
        own system's user identifier, 

        such as when displaying Featurebase data alongside your user's
        information in your own application.


        ### Version Availability


        This endpoint is only available in API version 2026-01-01.nova and
        newer.
      tags:
        - Contacts
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/FeaturebaseVersion'
        - schema:
            type: string
            maxLength: 255
            description: External user ID from your system
            example: usr_12345
          required: true
          name: userId
          in: path
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Contact'
                  - type: object
        '404':
          description: |-
            Not Found

            Possible error codes:
            - `contact_not_found`: No contact exists with this user ID
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - invalid_request_error
                        description: The type of error returned
                        example: invalid_request_error
                      code:
                        type: string
                        enum:
                          - contact_not_found
                        description: Machine-readable error code
                        example: contact_not_found
                      message:
                        type: string
                        description: Human-readable error message
                        example: An error occurred
                      param:
                        type: string
                        description: The parameter that caused the error (if applicable)
                        example: id
                      status:
                        type: number
                        enum:
                          - 404
                        description: HTTP status code
                        example: 404
                    required:
                      - type
                      - code
                      - message
                      - status
                required:
                  - error
    delete:
      operationId: deleteContactByUserId
      summary: Delete contact by external user ID
      description: >-
        Permanently deletes a contact by their external user ID.


        **Important:** This endpoint only deletes customers (type: "customer").
        Leads cannot be deleted using this endpoint.


        ### Path Parameters


        - `userId` - The external user ID from your system


        ### Deletion Behavior


        When a contact is deleted:

        - The contact record is permanently removed

        - Associated data cleanup is triggered asynchronously

        - Comments and posts created by the contact are handled according to
        retention policies


        ### Response


        Returns a deletion confirmation object:

        - `id` - The ID of the deleted contact

        - `object` - Always "contact"

        - `deleted` - Always `true`


        ### Example Response


        ```json

        {
          "id": "676f0f6765bdaa7d7d760f88",
          "object": "contact",
          "deleted": true
        }

        ```


        ### Use Case


        Use this endpoint when you need to delete a contact using your own
        system's user identifier,

        such as when a user deletes their account in your application.


        ### Version Availability


        This endpoint is only available in API version 2026-01-01.nova and
        newer.
      tags:
        - Contacts
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/FeaturebaseVersion'
        - schema:
            type: string
            maxLength: 255
            description: External user ID from your system
            example: usr_12345
          required: true
          name: userId
          in: path
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeletedContact'
        '400':
          description: |-
            Bad Request

            Possible error codes:
            - `invalid_request`: Contact is not a customer
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - invalid_request_error
                        description: The type of error returned
                        example: invalid_request_error
                      code:
                        type: string
                        enum:
                          - invalid_request
                        description: Machine-readable error code
                        example: invalid_request
                      message:
                        type: string
                        description: Human-readable error message
                        example: An error occurred
                      param:
                        type: string
                        description: The parameter that caused the error (if applicable)
                        example: id
                      status:
                        type: number
                        enum:
                          - 400
                        description: HTTP status code
                        example: 400
                    required:
                      - type
                      - code
                      - message
                      - status
                required:
                  - error
        '404':
          description: |-
            Not Found

            Possible error codes:
            - `contact_not_found`: No contact exists with this user ID
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - invalid_request_error
                        description: The type of error returned
                        example: invalid_request_error
                      code:
                        type: string
                        enum:
                          - contact_not_found
                        description: Machine-readable error code
                        example: contact_not_found
                      message:
                        type: string
                        description: Human-readable error message
                        example: An error occurred
                      param:
                        type: string
                        description: The parameter that caused the error (if applicable)
                        example: id
                      status:
                        type: number
                        enum:
                          - 404
                        description: HTTP status code
                        example: 404
                    required:
                      - type
                      - code
                      - message
                      - status
                required:
                  - error
  /v2/contacts/{id}/block:
    post:
      operationId: blockContactById
      summary: Block a contact
      description: >-
        Blocks a contact by their Featurebase ID from the messenger/inbox.


        ### Path Parameters


        - `id` - The Featurebase internal ID of the contact (MongoDB ObjectId)


        ### Supported Contact Types


        This endpoint blocks both:

        - **Customers** - Users with registered accounts

        - **Leads** - Anonymous or unregistered visitors


        ### Blocking Behavior


        When a contact is blocked:

        - The contact cannot send new messages via messenger

        - Existing conversations are not deleted but no new messages can be
        added by the blocked user

        - The block can be removed by unblocking the contact


        ### Response


        Returns a block confirmation object:

        - `id` - The ID of the blocked contact

        - `object` - Always "contact"

        - `blocked` - Always `true`


        ### Example Response


        ```json

        {
          "id": "507f1f77bcf86cd799439011",
          "object": "contact",
          "blocked": true
        }

        ```


        ### Version Availability


        This endpoint is only available in API version 2026-01-01.nova and
        newer.
      tags:
        - Contacts
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/FeaturebaseVersion'
        - schema:
            type: string
            description: Featurebase contact ID
            example: 507f1f77bcf86cd799439011
          required: true
          name: id
          in: path
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BlockedContact'
        '400':
          description: |-
            Bad Request

            Possible error codes:
            - `invalid_id`: The contact ID format is invalid
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - invalid_request_error
                        description: The type of error returned
                        example: invalid_request_error
                      code:
                        type: string
                        enum:
                          - invalid_id
                        description: Machine-readable error code
                        example: invalid_id
                      message:
                        type: string
                        description: Human-readable error message
                        example: An error occurred
                      param:
                        type: string
                        description: The parameter that caused the error (if applicable)
                        example: id
                      status:
                        type: number
                        enum:
                          - 400
                        description: HTTP status code
                        example: 400
                    required:
                      - type
                      - code
                      - message
                      - status
                required:
                  - error
        '404':
          description: |-
            Not Found

            Possible error codes:
            - `contact_not_found`: No contact exists with this ID
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - invalid_request_error
                        description: The type of error returned
                        example: invalid_request_error
                      code:
                        type: string
                        enum:
                          - contact_not_found
                        description: Machine-readable error code
                        example: contact_not_found
                      message:
                        type: string
                        description: Human-readable error message
                        example: An error occurred
                      param:
                        type: string
                        description: The parameter that caused the error (if applicable)
                        example: id
                      status:
                        type: number
                        enum:
                          - 404
                        description: HTTP status code
                        example: 404
                    required:
                      - type
                      - code
                      - message
                      - status
                required:
                  - error
  /v2/contacts/{id}/unblock:
    post:
      operationId: unblockContactById
      summary: Unblock a contact
      description: >-
        Unblocks a contact by their Featurebase ID from the messenger/inbox.


        ### Path Parameters


        - `id` - The Featurebase internal ID of the contact (MongoDB ObjectId)


        ### Supported Contact Types


        This endpoint unblocks both:

        - **Customers** - Users with registered accounts

        - **Leads** - Anonymous or unregistered visitors


        ### Unblocking Behavior


        When a contact is unblocked:

        - The contact can resume sending messages via messenger

        - Previously blocked conversations remain intact

        - The contact regains full messenger functionality


        ### Response


        Returns an unblock confirmation object:

        - `id` - The ID of the unblocked contact

        - `object` - Always "contact"

        - `unblocked` - Always `true`


        ### Example Response


        ```json

        {
          "id": "507f1f77bcf86cd799439011",
          "object": "contact",
          "unblocked": true
        }

        ```


        ### Version Availability


        This endpoint is only available in API version 2026-01-01.nova and
        newer.
      tags:
        - Contacts
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/FeaturebaseVersion'
        - schema:
            type: string
            description: Featurebase contact ID
            example: 507f1f77bcf86cd799439011
          required: true
          name: id
          in: path
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnblockedContact'
        '400':
          description: |-
            Bad Request

            Possible error codes:
            - `invalid_id`: The contact ID format is invalid
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - invalid_request_error
                        description: The type of error returned
                        example: invalid_request_error
                      code:
                        type: string
                        enum:
                          - invalid_id
                        description: Machine-readable error code
                        example: invalid_id
                      message:
                        type: string
                        description: Human-readable error message
                        example: An error occurred
                      param:
                        type: string
                        description: The parameter that caused the error (if applicable)
                        example: id
                      status:
                        type: number
                        enum:
                          - 400
                        description: HTTP status code
                        example: 400
                    required:
                      - type
                      - code
                      - message
                      - status
                required:
                  - error
        '404':
          description: |-
            Not Found

            Possible error codes:
            - `contact_not_found`: No contact exists with this ID
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - invalid_request_error
                        description: The type of error returned
                        example: invalid_request_error
                      code:
                        type: string
                        enum:
                          - contact_not_found
                        description: Machine-readable error code
                        example: contact_not_found
                      message:
                        type: string
                        description: Human-readable error message
                        example: An error occurred
                      param:
                        type: string
                        description: The parameter that caused the error (if applicable)
                        example: id
                      status:
                        type: number
                        enum:
                          - 404
                        description: HTTP status code
                        example: 404
                    required:
                      - type
                      - code
                      - message
                      - status
                required:
                  - error
  /v2/teams:
    get:
      operationId: listTeams
      summary: List all teams
      description: >-
        Returns all teams in your organization.


        ### Response Structure


        The response includes:

        - `object` - Always "list"

        - `data` - Array of team objects


        ### Team Object


        Each team includes:

        - `id` - Unique team identifier

        - `name` - Team display name

        - `color` - Team color in hex format

        - `icon` - Team icon (emoji, predefined, or external URL)

        - `members` - Array of admin IDs who are members of this team


        ### Example Response


        ```json

        {
          "object": "list",
          "data": [
            {
              "object": "team",
              "id": "507f1f77bcf86cd799439011",
              "name": "Support Team",
              "color": "#3B82F6",
              "icon": {
                "value": "👥",
                "type": "emoji"
              },
              "members": ["5fef50c5e9458a0012f82456", "5fef50c5e9458a0012f82457"]
            }
          ]
        }

        ```


        ### Version Availability


        This endpoint is only available in API version 2026-01-01.nova and
        newer.
      tags:
        - Teams
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/FeaturebaseVersion'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TeamList'
        '400':
          description: Bad Request - Validation error or invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
        '404':
          description: Not Found - Resource does not exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerError'
  /v2/teams/{id}:
    get:
      operationId: getTeamById
      summary: Get team by ID
      description: >-
        Retrieves a single team by its Featurebase ID.


        ### Path Parameters


        - `id` - The Featurebase internal ID of the team (MongoDB ObjectId)


        ### Response


        Returns a team object with:

        - `id` - Unique team identifier

        - `name` - Team display name

        - `color` - Team color in hex format

        - `icon` - Team icon (emoji, predefined, or external URL)

        - `members` - Array of admin IDs who are members of this team


        ### Example Response


        ```json

        {
          "object": "team",
          "id": "507f1f77bcf86cd799439011",
          "name": "Support Team",
          "color": "#3B82F6",
          "icon": {
            "value": "👥",
            "type": "emoji"
          },
          "members": ["5fef50c5e9458a0012f82456", "5fef50c5e9458a0012f82457"]
        }

        ```


        ### Error Responses


        - **404 Not Found** - Team with the specified ID does not exist


        ### Version Availability


        This endpoint is only available in API version 2026-01-01.nova and
        newer.
      tags:
        - Teams
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/FeaturebaseVersion'
        - schema:
            type: string
            description: The Featurebase internal ID of the team (MongoDB ObjectId)
            example: 507f1f77bcf86cd799439011
          required: true
          name: id
          in: path
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Team'
        '400':
          description: |-
            Bad Request

            Possible error codes:
            - `invalid_id`: The team ID format is invalid
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - invalid_request_error
                        description: The type of error returned
                        example: invalid_request_error
                      code:
                        type: string
                        enum:
                          - invalid_id
                        description: Machine-readable error code
                        example: invalid_id
                      message:
                        type: string
                        description: Human-readable error message
                        example: An error occurred
                      param:
                        type: string
                        description: The parameter that caused the error (if applicable)
                        example: id
                      status:
                        type: number
                        enum:
                          - 400
                        description: HTTP status code
                        example: 400
                    required:
                      - type
                      - code
                      - message
                      - status
                required:
                  - error
        '404':
          description: |-
            Not Found

            Possible error codes:
            - `team_not_found`: No team exists with this ID
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - invalid_request_error
                        description: The type of error returned
                        example: invalid_request_error
                      code:
                        type: string
                        enum:
                          - team_not_found
                        description: Machine-readable error code
                        example: team_not_found
                      message:
                        type: string
                        description: Human-readable error message
                        example: An error occurred
                      param:
                        type: string
                        description: The parameter that caused the error (if applicable)
                        example: id
                      status:
                        type: number
                        enum:
                          - 404
                        description: HTTP status code
                        example: 404
                    required:
                      - type
                      - code
                      - message
                      - status
                required:
                  - error
  /v2/companies:
    get:
      operationId: listCompanies
      summary: List all companies
      description: >-
        Returns all companies in your organization with cursor-based pagination.


        ### Query Parameters


        - `limit` - Number of companies to return (1-100, default: 10)

        - `cursor` - Opaque cursor from a previous response for pagination


        ### Response Structure


        The response includes:

        - `object` - Always "list"

        - `data` - Array of company objects

        - `nextCursor` - Cursor for the next page (null if no more results)


        ### Company Object


        Each company includes:

        - `id` - Featurebase internal ID (MongoDB ObjectId)

        - `companyId` - External company ID from your system

        - `name` - Company name

        - `monthlySpend` - Monthly spend/revenue

        - `industry` - Industry

        - `website` - Company website URL

        - `plan` - Plan/tier name

        - `linkedUsers` - Number of users linked to this company

        - `companySize` - Employee headcount

        - `lastActivity` - Last activity timestamp

        - `customFields` - Custom field values

        - `createdAt` - Creation timestamp

        - `updatedAt` - Last update timestamp


        ### Example Response


        ```json

        {
          "object": "list",
          "data": [
            {
              "object": "company",
              "id": "507f1f77bcf86cd799439011",
              "companyId": "comp_12345",
              "name": "Acme Inc",
              "monthlySpend": 5000,
              "industry": "Technology",
              "website": "https://acme.com",
              "plan": "enterprise",
              "linkedUsers": 15,
              "companySize": 250,
              "lastActivity": "2025-01-15T00:00:00.000Z",
              "customFields": { "location": "Europe" },
              "createdAt": "2025-01-01T12:00:00.000Z",
              "updatedAt": "2025-01-10T15:30:00.000Z"
            }
          ],
          "nextCursor": "eyJpZCI6IjUwN2YxZjc3YmNmODZjZDc5OTQzOTAxMSJ9"
        }

        ```


        ### Version Availability


        This endpoint is only available in API version 2026-01-01.nova and
        newer.
      tags:
        - Companies
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/FeaturebaseVersion'
        - schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 10
            description: >-
              A limit on the number of companies to be returned, between 1 and
              100.
            example: 10
          required: false
          name: limit
          in: query
        - schema:
            type: string
            maxLength: 512
            description: >-
              An opaque cursor for pagination. Use the nextCursor value from a
              previous response to fetch the next page of results.
            example: eyJpZCI6IjUwN2YxZjc3YmNmODZjZDc5OTQzOTAxMSJ9
          required: false
          name: cursor
          in: query
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompanyList'
        '400':
          description: |-
            Bad Request

            Possible error codes:
            - `invalid_cursor`: The pagination cursor is malformed or expired
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - invalid_request_error
                        description: The type of error returned
                        example: invalid_request_error
                      code:
                        type: string
                        enum:
                          - invalid_cursor
                        description: Machine-readable error code
                        example: invalid_cursor
                      message:
                        type: string
                        description: Human-readable error message
                        example: An error occurred
                      param:
                        type: string
                        description: The parameter that caused the error (if applicable)
                        example: id
                      status:
                        type: number
                        enum:
                          - 400
                        description: HTTP status code
                        example: 400
                    required:
                      - type
                      - code
                      - message
                      - status
                required:
                  - error
    post:
      operationId: upsertCompany
      summary: Create or update a company
      description: >-
        Creates a new company or updates an existing one.


        Uses the external `companyId` as the unique identifier for upsert
        matching.

        If a company with the given `companyId` already exists, it will be
        updated.

        Otherwise, a new company will be created.


        ### Request Body


        | Field | Type | Required | Description |

        |-------|------|----------|-------------|

        | `companyId` | string | Yes | External company ID from your system
        (unique identifier) |

        | `name` | string | Yes | Company name |

        | `monthlySpend` | number | No | Monthly spend/revenue from this company
        |

        | `industry` | string | No | Industry the company operates in |

        | `website` | string | No | Company website URL |

        | `plan` | string | No | Current plan/subscription name |

        | `companySize` | number | No | Number of employees |

        | `createdAt` | string | No | When the company was created (ISO 8601) |

        | `customFields` | object | No | Custom field values |


        ### Example Request


        ```json

        {
          "companyId": "comp_12345",
          "name": "Acme Inc",
          "monthlySpend": 5000,
          "industry": "Technology",
          "website": "https://acme.com",
          "plan": "enterprise",
          "companySize": 250,
          "customFields": {
            "region": "EMEA",
            "tier": "gold"
          }
        }

        ```


        ### Example Response


        ```json

        {
          "object": "company",
          "id": "507f1f77bcf86cd799439011",
          "companyId": "comp_12345",
          "name": "Acme Inc",
          "monthlySpend": 5000,
          "industry": "Technology",
          "website": "https://acme.com",
          "plan": "enterprise",
          "linkedUsers": 1,
          "companySize": 250,
          "lastActivity": "2025-01-15T00:00:00.000Z",
          "customFields": { "region": "EMEA", "tier": "gold" },
          "createdAt": "2025-01-01T12:00:00.000Z",
          "updatedAt": "2025-01-15T10:30:00.000Z"
        }

        ```


        ### Error Responses


        - **400 Bad Request** - Invalid company data


        ### Version Availability


        This endpoint is only available in API version 2026-01-01.nova and
        newer.
      tags:
        - Companies
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/FeaturebaseVersion'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpsertCompanyBody'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Company'
        '400':
          description: |-
            Bad Request

            Possible error codes:
            - `invalid_request`: Invalid company data
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - invalid_request_error
                        description: The type of error returned
                        example: invalid_request_error
                      code:
                        type: string
                        enum:
                          - invalid_request
                        description: Machine-readable error code
                        example: invalid_request
                      message:
                        type: string
                        description: Human-readable error message
                        example: An error occurred
                      param:
                        type: string
                        description: The parameter that caused the error (if applicable)
                        example: id
                      status:
                        type: number
                        enum:
                          - 400
                        description: HTTP status code
                        example: 400
                    required:
                      - type
                      - code
                      - message
                      - status
                required:
                  - error
  /v2/companies/{id}:
    get:
      operationId: getCompanyById
      summary: Get company by ID
      description: >-
        Retrieves a single company by its Featurebase ID.


        ### Path Parameters


        - `id` - The Featurebase internal ID of the company (MongoDB ObjectId)


        ### Response


        Returns a company object with:

        - `id` - Featurebase internal ID

        - `companyId` - External company ID from your system

        - `name` - Company name

        - `monthlySpend` - Monthly spend/revenue

        - `industry` - Industry

        - `website` - Company website URL

        - `plan` - Plan/tier name

        - `linkedUsers` - Number of users linked to this company

        - `companySize` - Employee headcount

        - `lastActivity` - Last activity timestamp

        - `customFields` - Custom field values

        - `createdAt` - Creation timestamp

        - `updatedAt` - Last update timestamp


        ### Example Response


        ```json

        {
          "object": "company",
          "id": "507f1f77bcf86cd799439011",
          "companyId": "comp_12345",
          "name": "Acme Inc",
          "monthlySpend": 5000,
          "industry": "Technology",
          "website": "https://acme.com",
          "plan": "enterprise",
          "linkedUsers": 15,
          "companySize": 250,
          "lastActivity": "2025-01-15T00:00:00.000Z",
          "customFields": { "location": "Europe" },
          "createdAt": "2025-01-01T12:00:00.000Z",
          "updatedAt": "2025-01-10T15:30:00.000Z"
        }

        ```


        ### Error Responses


        - **404 Not Found** - Company with the specified ID does not exist


        ### Version Availability


        This endpoint is only available in API version 2026-01-01.nova and
        newer.
      tags:
        - Companies
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/FeaturebaseVersion'
        - schema:
            type: string
            description: The Featurebase internal ID of the company (MongoDB ObjectId)
            example: 507f1f77bcf86cd799439011
          required: true
          name: id
          in: path
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Company'
        '400':
          description: |-
            Bad Request

            Possible error codes:
            - `invalid_id`: The company ID format is invalid
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - invalid_request_error
                        description: The type of error returned
                        example: invalid_request_error
                      code:
                        type: string
                        enum:
                          - invalid_id
                        description: Machine-readable error code
                        example: invalid_id
                      message:
                        type: string
                        description: Human-readable error message
                        example: An error occurred
                      param:
                        type: string
                        description: The parameter that caused the error (if applicable)
                        example: id
                      status:
                        type: number
                        enum:
                          - 400
                        description: HTTP status code
                        example: 400
                    required:
                      - type
                      - code
                      - message
                      - status
                required:
                  - error
        '404':
          description: |-
            Not Found

            Possible error codes:
            - `company_not_found`: No company exists with this ID
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - invalid_request_error
                        description: The type of error returned
                        example: invalid_request_error
                      code:
                        type: string
                        enum:
                          - company_not_found
                        description: Machine-readable error code
                        example: company_not_found
                      message:
                        type: string
                        description: Human-readable error message
                        example: An error occurred
                      param:
                        type: string
                        description: The parameter that caused the error (if applicable)
                        example: id
                      status:
                        type: number
                        enum:
                          - 404
                        description: HTTP status code
                        example: 404
                    required:
                      - type
                      - code
                      - message
                      - status
                required:
                  - error
    delete:
      operationId: deleteCompanyById
      summary: Delete a company
      description: >-
        Deletes a company by its Featurebase ID.


        This will also remove the company from all linked users' associations.


        ### Path Parameters


        - `id` - The Featurebase internal ID of the company (MongoDB ObjectId)


        ### Response


        Returns a deletion confirmation object:


        ```json

        {
          "id": "507f1f77bcf86cd799439011",
          "object": "company",
          "deleted": true
        }

        ```


        ### Error Responses


        - **404 Not Found** - Company with the specified ID does not exist


        ### Version Availability


        This endpoint is only available in API version 2026-01-01.nova and
        newer.
      tags:
        - Companies
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/FeaturebaseVersion'
        - schema:
            type: string
            description: The Featurebase internal ID of the company (MongoDB ObjectId)
            example: 507f1f77bcf86cd799439011
          required: true
          name: id
          in: path
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeletedCompany'
        '400':
          description: |-
            Bad Request

            Possible error codes:
            - `invalid_id`: The company ID format is invalid
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - invalid_request_error
                        description: The type of error returned
                        example: invalid_request_error
                      code:
                        type: string
                        enum:
                          - invalid_id
                        description: Machine-readable error code
                        example: invalid_id
                      message:
                        type: string
                        description: Human-readable error message
                        example: An error occurred
                      param:
                        type: string
                        description: The parameter that caused the error (if applicable)
                        example: id
                      status:
                        type: number
                        enum:
                          - 400
                        description: HTTP status code
                        example: 400
                    required:
                      - type
                      - code
                      - message
                      - status
                required:
                  - error
        '404':
          description: |-
            Not Found

            Possible error codes:
            - `company_not_found`: No company exists with this ID
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - invalid_request_error
                        description: The type of error returned
                        example: invalid_request_error
                      code:
                        type: string
                        enum:
                          - company_not_found
                        description: Machine-readable error code
                        example: company_not_found
                      message:
                        type: string
                        description: Human-readable error message
                        example: An error occurred
                      param:
                        type: string
                        description: The parameter that caused the error (if applicable)
                        example: id
                      status:
                        type: number
                        enum:
                          - 404
                        description: HTTP status code
                        example: 404
                    required:
                      - type
                      - code
                      - message
                      - status
                required:
                  - error
  /v2/companies/{id}/contacts:
    get:
      operationId: listCompanyContacts
      summary: List contacts attached to a company
      description: >-
        Returns all contacts (customers) attached to a specific company.


        Only returns contacts with type "customer" that have the company in
        their `companyIds` array.

        Uses cursor-based pagination.


        ### Path Parameters


        - `id` - The Featurebase internal ID of the company (MongoDB ObjectId)


        ### Query Parameters


        - `limit` - Number of contacts to return (1-100, default: 10)

        - `cursor` - Opaque cursor from a previous response for pagination


        ### Response Structure


        The response includes:

        - `object` - Always "list"

        - `data` - Array of contact objects

        - `nextCursor` - Cursor for the next page (null if no more results)


        ### Example Response


        ```json

        {
          "object": "list",
          "data": [
            {
              "object": "contact",
              "id": "507f1f77bcf86cd799439011",
              "userId": "usr_12345",
              "email": "john@acme.com",
              "name": "John Doe",
              "type": "customer",
              "companies": [...],
              "createdAt": "2025-01-01T12:00:00.000Z"
            }
          ],
          "nextCursor": "eyJpZCI6IjUwN2YxZjc3YmNmODZjZDc5OTQzOTAxMSJ9"
        }

        ```


        ### Error Responses


        - **404 Not Found** - Company with the specified ID does not exist


        ### Version Availability


        This endpoint is only available in API version 2026-01-01.nova and
        newer.
      tags:
        - Companies
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/FeaturebaseVersion'
        - schema:
            type: string
            description: The Featurebase internal ID of the company (MongoDB ObjectId)
            example: 507f1f77bcf86cd799439011
          required: true
          name: id
          in: path
        - schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 10
            description: >-
              A limit on the number of contacts to be returned, between 1 and
              100.
            example: 10
          required: false
          name: limit
          in: query
        - schema:
            type: string
            maxLength: 512
            description: >-
              An opaque cursor for pagination. Use the nextCursor value from a
              previous response to fetch the next page of results.
            example: eyJpZCI6IjUwN2YxZjc3YmNmODZjZDc5OTQzOTAxMSJ9
          required: false
          name: cursor
          in: query
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContactList'
        '400':
          description: |-
            Bad Request

            Possible error codes:
            - `invalid_id`: The company ID format is invalid
            - `invalid_cursor`: The pagination cursor is malformed or expired
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - invalid_request_error
                        description: The type of error returned
                        example: invalid_request_error
                      code:
                        type: string
                        enum:
                          - invalid_id
                          - invalid_cursor
                        description: Machine-readable error code
                        example: invalid_id
                      message:
                        type: string
                        description: Human-readable error message
                        example: An error occurred
                      param:
                        type: string
                        description: The parameter that caused the error (if applicable)
                        example: id
                      status:
                        type: number
                        enum:
                          - 400
                        description: HTTP status code
                        example: 400
                    required:
                      - type
                      - code
                      - message
                      - status
                required:
                  - error
        '404':
          description: |-
            Not Found

            Possible error codes:
            - `company_not_found`: No company exists with this ID
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - invalid_request_error
                        description: The type of error returned
                        example: invalid_request_error
                      code:
                        type: string
                        enum:
                          - company_not_found
                        description: Machine-readable error code
                        example: company_not_found
                      message:
                        type: string
                        description: Human-readable error message
                        example: An error occurred
                      param:
                        type: string
                        description: The parameter that caused the error (if applicable)
                        example: id
                      status:
                        type: number
                        enum:
                          - 404
                        description: HTTP status code
                        example: 404
                    required:
                      - type
                      - code
                      - message
                      - status
                required:
                  - error
    post:
      operationId: attachContactToCompany
      summary: Attach a contact to a company
      description: >-
        Attaches a contact (customer) to a company.


        Adds the company to the contact's `companyIds` array and embedded
        `companies` array.

        This operation is **additive** - existing company associations are
        preserved.

        Also increments the `linkedUsers` count on the company.


        ### Path Parameters


        - `id` - The Featurebase internal ID of the company (MongoDB ObjectId)


        ### Request Body


        | Field | Type | Required | Description |

        |-------|------|----------|-------------|

        | `contactId` | string | Yes | The Featurebase internal ID of the
        contact to attach (MongoDB ObjectId) |


        ### Example Request


        ```json

        {
          "contactId": "507f1f77bcf86cd799439012"
        }

        ```


        ### Response


        Returns the updated contact object with the new company association.


        ### Example Response


        ```json

        {
          "object": "contact",
          "id": "507f1f77bcf86cd799439012",
          "userId": "usr_12345",
          "email": "john@acme.com",
          "name": "John Doe",
          "type": "customer",
          "companies": [
            {
              "object": "company",
              "id": "507f1f77bcf86cd799439011",
              "companyId": "comp_12345",
              "name": "Acme Inc"
            }
          ]
        }

        ```


        ### Error Responses


        - **404 Not Found** - Company or contact does not exist


        ### Version Availability


        This endpoint is only available in API version 2026-01-01.nova and
        newer.
      tags:
        - Companies
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/FeaturebaseVersion'
        - schema:
            type: string
            description: The Featurebase internal ID of the company (MongoDB ObjectId)
            example: 507f1f77bcf86cd799439011
          required: true
          name: id
          in: path
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AttachContactToCompanyBody'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Contact'
                  - type: object
        '400':
          description: |-
            Bad Request

            Possible error codes:
            - `invalid_id`: The company or contact ID format is invalid
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - invalid_request_error
                        description: The type of error returned
                        example: invalid_request_error
                      code:
                        type: string
                        enum:
                          - invalid_id
                        description: Machine-readable error code
                        example: invalid_id
                      message:
                        type: string
                        description: Human-readable error message
                        example: An error occurred
                      param:
                        type: string
                        description: The parameter that caused the error (if applicable)
                        example: id
                      status:
                        type: number
                        enum:
                          - 400
                        description: HTTP status code
                        example: 400
                    required:
                      - type
                      - code
                      - message
                      - status
                required:
                  - error
        '404':
          description: |-
            Not Found

            Possible error codes:
            - `company_not_found`: No company exists with this ID
            - `contact_not_found`: No contact exists with this ID
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - invalid_request_error
                        description: The type of error returned
                        example: invalid_request_error
                      code:
                        type: string
                        enum:
                          - company_not_found
                          - contact_not_found
                        description: Machine-readable error code
                        example: company_not_found
                      message:
                        type: string
                        description: Human-readable error message
                        example: An error occurred
                      param:
                        type: string
                        description: The parameter that caused the error (if applicable)
                        example: id
                      status:
                        type: number
                        enum:
                          - 404
                        description: HTTP status code
                        example: 404
                    required:
                      - type
                      - code
                      - message
                      - status
                required:
                  - error
  /v2/companies/{id}/contacts/{contactId}:
    delete:
      operationId: removeContactFromCompany
      summary: Remove a contact from a company
      description: >-
        Removes a contact (customer) from a company.


        Removes the company from the contact's `companyIds` array and embedded
        `companies` array.

        Also decrements the `linkedUsers` count on the company.


        ### Path Parameters


        - `id` - The Featurebase internal ID of the company (MongoDB ObjectId)

        - `contactId` - The Featurebase internal ID of the contact to remove
        (MongoDB ObjectId)


        ### Response


        Returns the updated contact object with the company removed.


        ### Example Response


        ```json

        {
          "object": "contact",
          "id": "507f1f77bcf86cd799439012",
          "userId": "usr_12345",
          "email": "john@acme.com",
          "name": "John Doe",
          "type": "customer",
          "companies": []
        }

        ```


        ### Error Responses


        - **400 Bad Request** - Contact is not attached to this company

        - **404 Not Found** - Company or contact does not exist


        ### Version Availability


        This endpoint is only available in API version 2026-01-01.nova and
        newer.
      tags:
        - Companies
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/FeaturebaseVersion'
        - schema:
            type: string
            description: The Featurebase internal ID of the company (MongoDB ObjectId)
            example: 507f1f77bcf86cd799439011
          required: true
          name: id
          in: path
        - schema:
            type: string
            description: >-
              The Featurebase internal ID of the contact to remove (MongoDB
              ObjectId)
            example: 507f1f77bcf86cd799439012
          required: true
          name: contactId
          in: path
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Contact'
                  - type: object
        '400':
          description: |-
            Bad Request

            Possible error codes:
            - `invalid_id`: The company or contact ID format is invalid
            - `contact_not_attached`: Contact is not attached to this company
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - invalid_request_error
                        description: The type of error returned
                        example: invalid_request_error
                      code:
                        type: string
                        enum:
                          - invalid_id
                          - contact_not_attached
                        description: Machine-readable error code
                        example: invalid_id
                      message:
                        type: string
                        description: Human-readable error message
                        example: An error occurred
                      param:
                        type: string
                        description: The parameter that caused the error (if applicable)
                        example: id
                      status:
                        type: number
                        enum:
                          - 400
                        description: HTTP status code
                        example: 400
                    required:
                      - type
                      - code
                      - message
                      - status
                required:
                  - error
        '404':
          description: |-
            Not Found

            Possible error codes:
            - `company_not_found`: No company exists with this ID
            - `contact_not_found`: No contact exists with this ID
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - invalid_request_error
                        description: The type of error returned
                        example: invalid_request_error
                      code:
                        type: string
                        enum:
                          - company_not_found
                          - contact_not_found
                        description: Machine-readable error code
                        example: company_not_found
                      message:
                        type: string
                        description: Human-readable error message
                        example: An error occurred
                      param:
                        type: string
                        description: The parameter that caused the error (if applicable)
                        example: id
                      status:
                        type: number
                        enum:
                          - 404
                        description: HTTP status code
                        example: 404
                    required:
                      - type
                      - code
                      - message
                      - status
                required:
                  - error
  /v2/conversations:
    get:
      operationId: listConversations
      summary: List conversations
      description: >-
        Returns a list of conversations in your organization using cursor-based
        pagination.


        ### Query Parameters


        - `limit` - Number of conversations to return (1-100, default 10)

        - `cursor` - Cursor from previous response for pagination


        ### Response Format


        Returns a list object with:

        - `object` - Always "list"

        - `data` - Array of conversation objects

        - `nextCursor` - Cursor for the next page, or null if no more results


        ### Conversation Object


        Each conversation includes:

        - `id` - Unique conversation identifier (short ID)

        - `title` - Conversation title

        - `state` - Current state ("open", "closed", or "snoozed")

        - `priority` - Whether the conversation is marked as priority

        - `adminAssigneeId` - ID of assigned admin (if any)

        - `teamAssigneeId` - ID of assigned team (if any)

        - `participants` - Array of participants

        - `source` - Information about the first message

        - `createdAt` - Creation timestamp

        - `updatedAt` - Last update timestamp


        ### Example


        ```json

        {
          "object": "list",
          "data": [
            {
              "object": "conversation",
              "id": "12345",
              "title": "Question about pricing",
              "state": "open",
              "priority": false,
              "adminAssigneeId": null,
              "participants": [
                { "type": "customer", "id": "676f0f6765bdaa7d7d760f88" }
              ],
              ...
            }
          ],
          "nextCursor": "eyJpZCI6IjEyMzQ1In0="
        }

        ```


        ### Version Availability


        This endpoint is only available in API version 2026-01-01.nova and
        newer.
      tags:
        - Conversations
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/FeaturebaseVersion'
        - schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 10
            description: >-
              A limit on the number of objects to be returned, between 1 and
              100.
            example: 10
          required: false
          name: limit
          in: query
        - schema:
            type: string
            maxLength: 512
            description: >-
              An opaque cursor for pagination. Use the nextCursor value from a
              previous response to fetch the next page of results.
            example: eyJpZCI6IjEyMzQ1In0=
          required: false
          name: cursor
          in: query
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConversationList'
        '400':
          description: |-
            Bad Request

            Possible error codes:
            - `invalid_cursor`: The pagination cursor is malformed or expired
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - invalid_request_error
                        description: The type of error returned
                        example: invalid_request_error
                      code:
                        type: string
                        enum:
                          - invalid_cursor
                        description: Machine-readable error code
                        example: invalid_cursor
                      message:
                        type: string
                        description: Human-readable error message
                        example: An error occurred
                      param:
                        type: string
                        description: The parameter that caused the error (if applicable)
                        example: id
                      status:
                        type: number
                        enum:
                          - 400
                        description: HTTP status code
                        example: 400
                    required:
                      - type
                      - code
                      - message
                      - status
                required:
                  - error
    post:
      operationId: createConversation
      summary: Create a conversation
      description: >-
        Creates a new conversation. Supports both contact-initiated
        (customer/lead) and admin-initiated (outreach) conversations.


        ## Contact-Initiated Conversation


        For conversations started by a customer or lead:


        | Field | Type | Required | Description |

        |-------|------|----------|-------------|

        | `from.type` | string | Yes | Must be "contact" |

        | `from.id` | string | Yes | The Featurebase contact ID (24-character
        ObjectId) |

        | `bodyMarkdown` | string | Yes | The initial message content in
        markdown format. Images referenced by URL or as base64 data URIs will be
        automatically uploaded and stored. |

        | `channel` | string | No | The channel: "desktop" (default) or "email"
        |

        | `createdAt` | string | No | ISO timestamp for migrations |


        ### Example Contact-Initiated Request


        ```json

        {
          "from": {
            "type": "contact",
            "id": "676f0f6765bdaa7d7d760f88"
          },
          "bodyMarkdown": "Hello, I have a question about your product.",
          "channel": "desktop"
        }

        ```


        ## Admin-Initiated Outreach


        For outreach conversations started by an admin:


        | Field | Type | Required | Description |

        |-------|------|----------|-------------|

        | `from.type` | string | Yes | Must be "admin" |

        | `from.id` | string | Yes | The Featurebase admin ID (24-character
        ObjectId) |

        | `bodyMarkdown` | string | Yes | The initial message content in
        markdown format. Images referenced by URL or as base64 data URIs will be
        automatically uploaded and stored. |

        | `channel` | string | No | The channel: "desktop" (default) or "email"
        |

        | `recipients` | object | Yes | Recipients for the outreach |

        | `recipients.to` | object | Yes | Primary recipients |

        | `recipients.to.emails` | string[] | No* | Email addresses |

        | `recipients.to.ids` | string[] | No* | Featurebase contact IDs |

        | `recipients.cc` | object | No | CC recipients (same structure as "to")
        |

        | `recipients.bcc` | object | No | BCC recipients (same structure as
        "to") |

        | `subject` | string | No** | Email subject line |

        | `createdAt` | string | No | ISO timestamp for migrations |


        *At least one email or ID is required in `recipients.to`

        **Required when channel is "email"


        ### Example Admin Outreach (In-App)


        ```json

        {
          "from": {
            "type": "admin",
            "id": "507f1f77bcf86cd799439011"
          },
          "bodyMarkdown": "Hi! Just following up on your inquiry.",
          "channel": "desktop",
          "recipients": {
            "to": {
              "ids": ["676f0f6765bdaa7d7d760f88"]
            }
          }
        }

        ```


        ### Example Admin Outreach (Email)


        ```json

        {
          "from": {
            "type": "admin",
            "id": "507f1f77bcf86cd799439011"
          },
          "bodyMarkdown": "Hi! Just following up on your inquiry.",
          "channel": "email",
          "subject": "Following up on your inquiry",
          "recipients": {
            "to": {
              "emails": ["john@example.com"]
            },
            "cc": {
              "emails": ["manager@example.com"]
            }
          }
        }

        ```


        ### Response


        Returns the created conversation object with a **201 Created** status.


        ### Example Response


        ```json

        {
          "object": "conversation",
          "id": "12345",
          "state": "open",
          "priority": false,
          "adminAssigneeId": null,
          "participants": [
            { "type": "customer", "id": "676f0f6765bdaa7d7d760f88" }
          ],
          "source": {
            "channel": "desktop",
            "deliveredAs": "customer_initiated",
            "bodyHtml": "<p>Hello, I have a question about your product.</p>",
            "bodyMarkdown": "Hello, I have a question about your product.",
            "author": { "type": "customer", "id": "676f0f6765bdaa7d7d760f88" }
          },
          "createdAt": "2025-01-15T10:30:00.000Z",
          "updatedAt": "2025-01-15T10:30:00.000Z"
        }

        ```


        ### Version Availability


        This endpoint is only available in API version 2026-01-01.nova and
        newer.
      tags:
        - Conversations
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/FeaturebaseVersion'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateConversationBody'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Conversation'
        '400':
          description: |-
            Bad Request

            Possible error codes:
            - `invalid_content`: Invalid message content format
            - `missing_parameter`: Required field is missing
            - `invalid_parameter`: Invalid channel parameter
            - `undefined`: At least one recipient is required for admin outreach
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - invalid_request_error
                        description: The type of error returned
                        example: invalid_request_error
                      code:
                        type: string
                        enum:
                          - invalid_content
                          - missing_parameter
                          - invalid_parameter
                          - null
                        description: Machine-readable error code
                        example: invalid_content
                      message:
                        type: string
                        description: Human-readable error message
                        example: An error occurred
                      param:
                        type: string
                        description: The parameter that caused the error (if applicable)
                        example: id
                      status:
                        type: number
                        enum:
                          - 400
                        description: HTTP status code
                        example: 400
                    required:
                      - type
                      - code
                      - message
                      - status
                required:
                  - error
        '403':
          description: |-
            Forbidden

            Possible error codes:
            - `forbidden`: Admin is not a member of this organization
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - authorization_error
                        description: The type of error returned
                        example: authorization_error
                      code:
                        type: string
                        enum:
                          - forbidden
                        description: Machine-readable error code
                        example: forbidden
                      message:
                        type: string
                        description: Human-readable error message
                        example: An error occurred
                      param:
                        type: string
                        description: The parameter that caused the error (if applicable)
                        example: id
                      status:
                        type: number
                        enum:
                          - 403
                        description: HTTP status code
                        example: 403
                    required:
                      - type
                      - code
                      - message
                      - status
                required:
                  - error
        '404':
          description: >-
            Not Found


            Possible error codes:

            - `contact_not_found`: The contact initiating the conversation was
            not found

            - `admin_not_found`: The admin initiating the outreach was not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - invalid_request_error
                        description: The type of error returned
                        example: invalid_request_error
                      code:
                        type: string
                        enum:
                          - contact_not_found
                          - admin_not_found
                        description: Machine-readable error code
                        example: contact_not_found
                      message:
                        type: string
                        description: Human-readable error message
                        example: An error occurred
                      param:
                        type: string
                        description: The parameter that caused the error (if applicable)
                        example: id
                      status:
                        type: number
                        enum:
                          - 404
                        description: HTTP status code
                        example: 404
                    required:
                      - type
                      - code
                      - message
                      - status
                required:
                  - error
  /v2/conversations/{id}:
    get:
      operationId: getConversationById
      summary: Get conversation by ID
      description: >-
        Retrieves a single conversation by its ID, including conversation parts
        (messages).


        ### Path Parameters


        - `id` - The conversation ID (short ID)


        ### Hard Limit of 500 Parts


        The maximum number of conversation parts that can be returned via the
        API is **500**.

        If a conversation has more than 500 parts, only the **500 most recent**
        conversation parts will be returned.


        ### Response Format


        Returns a single conversation object with:

        - `object` - Always "conversation"

        - `id` - Unique conversation identifier (short ID)

        - `title` - Conversation title

        - `state` - Current state ("open", "closed", or "snoozed")

        - `priority` - Whether the conversation is marked as priority

        - `adminAssigneeId` - ID of assigned admin (if any)

        - `teamAssigneeId` - ID of assigned team (if any)

        - `participants` - Array of participants

        - `source` - Information about the first message

        - `conversationParts` - Array of conversation parts (messages, max 500)

        - `createdAt` - Creation timestamp

        - `updatedAt` - Last update timestamp


        ### Conversation Parts


        Each conversation part includes:

        - `object` - Always "conversation_part"

        - `id` - Unique part identifier

        - `partType` - Type of part (e.g., "user_msg", "admin_msg", "bot_msg")

        - `body` - Message body (HTML content)

        - `author` - Author information with name, email, and profile picture

        - `channel` - Channel through which the message was sent

        - `createdAt` - Creation timestamp

        - `updatedAt` - Last update timestamp


        ### Example


        ```json

        {
          "object": "conversation",
          "id": "12345",
          "title": "Question about pricing",
          "state": "open",
          "priority": false,
          "adminAssigneeId": "507f1f77bcf86cd799439011",
          "participants": [
            { "type": "customer", "id": "676f0f6765bdaa7d7d760f88" }
          ],
          "conversationParts": [
            {
              "object": "conversation_part",
              "id": "1",
              "partType": "user_msg",
              "bodyHtml": "<p>Hello, I have a question about your pricing plans.</p>",
              "bodyMarkdown": "Hello, I have a question about your pricing plans.",
              "author": {
                "type": "customer",
                "id": "676f0f6765bdaa7d7d760f88",
                "name": "John Doe",
                "email": "john@example.com"
              },
              "channel": "desktop",
              "createdAt": "2025-01-15T10:30:00.000Z",
              "updatedAt": "2025-01-15T10:30:00.000Z"
            },
            {
              "object": "conversation_part",
              "id": "2",
              "partType": "admin_msg",
              "bodyHtml": "<p>Hi John! I'd be happy to help you with pricing information.</p>",
              "bodyMarkdown": "Hi John! I'd be happy to help you with pricing information.",
              "author": {
                "type": "admin",
                "id": "507f1f77bcf86cd799439011",
                "name": "Support Agent"
              },
              "channel": "desktop",
              "createdAt": "2025-01-15T10:35:00.000Z",
              "updatedAt": "2025-01-15T10:35:00.000Z"
            }
          ],
          "createdAt": "2025-01-15T10:30:00.000Z",
          "updatedAt": "2025-01-15T10:35:00.000Z"
        }

        ```


        ### Version Availability


        This endpoint is only available in API version 2026-01-01.nova and
        newer.
      tags:
        - Conversations
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/FeaturebaseVersion'
        - schema:
            type: string
            minLength: 1
            maxLength: 16
            pattern: ^[a-zA-Z0-9]+$
            description: Conversation ID (short ID)
            example: '12345'
          required: true
          name: id
          in: path
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Conversation'
        '404':
          description: |-
            Not Found

            Possible error codes:
            - `conversation_not_found`: No conversation exists with this ID
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - invalid_request_error
                        description: The type of error returned
                        example: invalid_request_error
                      code:
                        type: string
                        enum:
                          - conversation_not_found
                        description: Machine-readable error code
                        example: conversation_not_found
                      message:
                        type: string
                        description: Human-readable error message
                        example: An error occurred
                      param:
                        type: string
                        description: The parameter that caused the error (if applicable)
                        example: id
                      status:
                        type: number
                        enum:
                          - 404
                        description: HTTP status code
                        example: 404
                    required:
                      - type
                      - code
                      - message
                      - status
                required:
                  - error
    delete:
      operationId: deleteConversation
      summary: Delete a conversation
      description: >-
        Permanently deletes a conversation by its short ID.


        ### Path Parameters


        - `id` - The conversation short ID (numeric)


        ### Response


        Returns a deletion confirmation object:


        ```json

        {
          "id": "12345",
          "object": "conversation",
          "deleted": true
        }

        ```


        ### Caution


        This operation is **irreversible**. The conversation and all its
        messages will be permanently deleted.


        ### Version Availability


        This endpoint is only available in API version 2026-01-01.nova and
        newer.
      tags:
        - Conversations
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/FeaturebaseVersion'
        - schema:
            type: string
            minLength: 1
            maxLength: 16
            pattern: ^[a-zA-Z0-9]+$
            description: Conversation ID (short ID)
            example: '12345'
          required: true
          name: id
          in: path
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeletedConversation'
        '404':
          description: |-
            Not Found

            Possible error codes:
            - `conversation_not_found`: No conversation exists with this ID
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - invalid_request_error
                        description: The type of error returned
                        example: invalid_request_error
                      code:
                        type: string
                        enum:
                          - conversation_not_found
                        description: Machine-readable error code
                        example: conversation_not_found
                      message:
                        type: string
                        description: Human-readable error message
                        example: An error occurred
                      param:
                        type: string
                        description: The parameter that caused the error (if applicable)
                        example: id
                      status:
                        type: number
                        enum:
                          - 404
                        description: HTTP status code
                        example: 404
                    required:
                      - type
                      - code
                      - message
                      - status
                required:
                  - error
    patch:
      operationId: updateConversation
      summary: Update a conversation
      description: >-
        Updates a conversation's properties. Supports partial updates - only
        provided fields will be updated.


        ### Path Parameters


        - `id` - The conversation ID (short ID)


        ### Request Body


        All fields are optional. Only provided fields will be updated.


        | Field | Type | Description |

        |-------|------|-------------|

        | `actingAdminId` | string | Admin ID performing the action (for
        attribution). If not provided, uses bot service user. Must be a member
        of the organization. |

        | `state` | string | Conversation state: "open", "closed", or "snoozed"
        |

        | `snoozedUntil` | string | ISO datetime when to unsnooze (required when
        state is "snoozed") |

        | `adminAssigneeId` | string/null | Admin ID to assign, or null to
        unassign |

        | `teamAssigneeId` | string/null | Team ID to assign, or null to
        unassign |

        | `title` | string | Conversation title |

        | `customAttributes` | object | Custom attributes to set on the
        conversation |

        | `markAsRead` | object | Mark conversation as read for specific users |


        ### markAsRead Object


        | Field | Type | Description |

        |-------|------|-------------|

        | `allAdmins` | boolean | If true, marks all admins with existing
        readReceipts as read |

        | `adminIds` | string[] | Array of specific admin IDs to mark as read |

        | `allContacts` | boolean | If true, marks all contacts with existing
        readReceipts as read |

        | `contactIds` | string[] | Array of specific contact IDs to mark as
        read |


        Note: Only users with existing read receipts will be updated. Use
        `allAdmins`/`allContacts` OR `adminIds`/`contactIds` - the "all" flags
        take precedence.


        ### Response


        Returns the updated conversation object.


        ### Example: Close a Conversation (with attribution)


        ```json

        {
          "actingAdminId": "507f1f77bcf86cd799439011",
          "state": "closed"
        }

        ```


        ### Example: Close a Conversation (bot user)


        ```json

        {
          "state": "closed"
        }

        ```


        ### Example: Snooze a Conversation


        ```json

        {
          "state": "snoozed",
          "snoozedUntil": "2025-01-20T10:00:00.000Z"
        }

        ```


        ### Example: Assign to an Admin


        ```json

        {
          "adminAssigneeId": "507f1f77bcf86cd799439011"
        }

        ```


        ### Example: Update Title and Custom Attributes


        ```json

        {
          "title": "Billing Issue - Priority",
          "customAttributes": {
            "priority_level": "high",
            "category": "billing"
          }
        }

        ```


        ### Example: Mark as Read (All Admins)


        ```json

        {
          "markAsRead": {
            "allAdmins": true
          }
        }

        ```


        ### Example: Mark as Read (All Contacts)


        ```json

        {
          "markAsRead": {
            "allContacts": true
          }
        }

        ```


        ### Example: Mark as Read (Specific IDs)


        ```json

        {
          "markAsRead": {
            "adminIds": ["507f1f77bcf86cd799439011"],
            "contactIds": ["676f0f6765bdaa7d7d760f88"]
          }
        }

        ```


        ### Version Availability


        This endpoint is only available in API version 2026-01-01.nova and
        newer.
      tags:
        - Conversations
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/FeaturebaseVersion'
        - schema:
            type: string
            minLength: 1
            maxLength: 16
            pattern: ^[a-zA-Z0-9]+$
            description: Conversation ID (short ID)
            example: '12345'
          required: true
          name: id
          in: path
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateConversationBody'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Conversation'
        '400':
          description: |-
            Bad Request

            Possible error codes:
            - `invalid_request`: Invalid update parameters
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - invalid_request_error
                        description: The type of error returned
                        example: invalid_request_error
                      code:
                        type: string
                        enum:
                          - invalid_request
                        description: Machine-readable error code
                        example: invalid_request
                      message:
                        type: string
                        description: Human-readable error message
                        example: An error occurred
                      param:
                        type: string
                        description: The parameter that caused the error (if applicable)
                        example: id
                      status:
                        type: number
                        enum:
                          - 400
                        description: HTTP status code
                        example: 400
                    required:
                      - type
                      - code
                      - message
                      - status
                required:
                  - error
        '403':
          description: |-
            Forbidden

            Possible error codes:
            - `forbidden`: Acting admin is not a member of this organization
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - authorization_error
                        description: The type of error returned
                        example: authorization_error
                      code:
                        type: string
                        enum:
                          - forbidden
                        description: Machine-readable error code
                        example: forbidden
                      message:
                        type: string
                        description: Human-readable error message
                        example: An error occurred
                      param:
                        type: string
                        description: The parameter that caused the error (if applicable)
                        example: id
                      status:
                        type: number
                        enum:
                          - 403
                        description: HTTP status code
                        example: 403
                    required:
                      - type
                      - code
                      - message
                      - status
                required:
                  - error
        '404':
          description: |-
            Not Found

            Possible error codes:
            - `conversation_not_found`: No conversation exists with this ID
            - `admin_not_found`: The acting admin was not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - invalid_request_error
                        description: The type of error returned
                        example: invalid_request_error
                      code:
                        type: string
                        enum:
                          - conversation_not_found
                          - admin_not_found
                        description: Machine-readable error code
                        example: conversation_not_found
                      message:
                        type: string
                        description: Human-readable error message
                        example: An error occurred
                      param:
                        type: string
                        description: The parameter that caused the error (if applicable)
                        example: id
                      status:
                        type: number
                        enum:
                          - 404
                        description: HTTP status code
                        example: 404
                    required:
                      - type
                      - code
                      - message
                      - status
                required:
                  - error
  /v2/conversations/{id}/reply:
    post:
      operationId: replyToConversation
      summary: Reply to a conversation
      description: >-
        Adds a reply to an existing conversation. Supports both contact
        (customer/lead) and admin replies.


        ### Path Parameters


        - `id` - The conversation ID (short ID)


        ### Request Body


        The request body varies based on who is sending the reply:


        #### Contact Reply (customer/lead)


        | Field | Type | Required | Description |

        |-------|------|----------|-------------|

        | `type` | string | Yes | Must be "contact" |

        | `userId` | string | No* | External user ID from your system |

        | `id` | string | No* | Featurebase contact ID (24-character ObjectId) |

        | `bodyMarkdown` | string | Yes | The message content in markdown
        format. Images referenced by URL or as base64 data URIs will be
        automatically uploaded and stored. |

        | `messageType` | string | Yes | Must be "reply" |


        *At least one of `userId` or `id` is required.


        #### Admin Reply


        | Field | Type | Required | Description |

        |-------|------|----------|-------------|

        | `type` | string | Yes | Must be "admin" |

        | `id` | string | Yes | Featurebase admin ID (24-character ObjectId) |

        | `bodyMarkdown` | string | Yes | The message content in markdown
        format. Images referenced by URL or as base64 data URIs will be
        automatically uploaded and stored. |

        | `messageType` | string | Yes | "reply" for customer-visible reply,
        "note" for internal note |


        ### Response


        Returns the created conversation part object with a **201 Created**
        status. The response includes both `bodyHtml` (with signed image URLs)
        and `bodyMarkdown` fields.


        ### Example Contact Reply


        ```json

        {
          "type": "contact",
          "userId": "user_123",
          "bodyMarkdown": "Thank you for your help!",
          "messageType": "reply"
        }

        ```


        ### Example Admin Reply


        ```json

        {
          "type": "admin",
          "id": "507f1f77bcf86cd799439011",
          "bodyMarkdown": "I'm happy to help! Here's what you need to do...",
          "messageType": "reply"
        }

        ```


        ### Example Admin Note (Internal)


        ```json

        {
          "type": "admin",
          "id": "507f1f77bcf86cd799439011",
          "bodyMarkdown": "Customer seems frustrated, escalating to tier 2.",
          "messageType": "note"
        }

        ```


        ### Example Response


        ```json

        {
          "object": "conversation_part",
          "id": "3",
          "partType": "user_msg",
          "bodyHtml": "<p>Thank you for your help!</p>",
          "bodyMarkdown": "Thank you for your help!",
          "author": {
            "type": "customer",
            "id": "676f0f6765bdaa7d7d760f88",
            "name": "John Doe",
            "email": "john@example.com"
          },
          "channel": "desktop",
          "createdAt": "2025-01-15T10:40:00.000Z",
          "updatedAt": "2025-01-15T10:40:00.000Z"
        }

        ```


        ### Version Availability


        This endpoint is only available in API version 2026-01-01.nova and
        newer.
      tags:
        - Conversations
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/FeaturebaseVersion'
        - schema:
            type: string
            minLength: 1
            maxLength: 16
            pattern: ^[a-zA-Z0-9]+$
            description: Conversation ID (short ID)
            example: '12345'
          required: true
          name: id
          in: path
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReplyToConversationBody'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConversationPart'
        '400':
          description: |-
            Bad Request

            Possible error codes:
            - `invalid_content`: Invalid message content format
            - `missing_parameter`: Required field is missing (userId or id)
            - `invalid_parameter`: Invalid channel parameter
            - `invalid_request`: Invalid reply type
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - invalid_request_error
                        description: The type of error returned
                        example: invalid_request_error
                      code:
                        type: string
                        enum:
                          - invalid_content
                          - missing_parameter
                          - invalid_parameter
                          - invalid_request
                        description: Machine-readable error code
                        example: invalid_content
                      message:
                        type: string
                        description: Human-readable error message
                        example: An error occurred
                      param:
                        type: string
                        description: The parameter that caused the error (if applicable)
                        example: id
                      status:
                        type: number
                        enum:
                          - 400
                        description: HTTP status code
                        example: 400
                    required:
                      - type
                      - code
                      - message
                      - status
                required:
                  - error
        '404':
          description: |-
            Not Found

            Possible error codes:
            - `conversation_not_found`: No conversation exists with this ID
            - `contact_not_found`: The contact sending the reply was not found
            - `admin_not_found`: The admin sending the reply was not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - invalid_request_error
                        description: The type of error returned
                        example: invalid_request_error
                      code:
                        type: string
                        enum:
                          - conversation_not_found
                          - contact_not_found
                          - admin_not_found
                        description: Machine-readable error code
                        example: conversation_not_found
                      message:
                        type: string
                        description: Human-readable error message
                        example: An error occurred
                      param:
                        type: string
                        description: The parameter that caused the error (if applicable)
                        example: id
                      status:
                        type: number
                        enum:
                          - 404
                        description: HTTP status code
                        example: 404
                    required:
                      - type
                      - code
                      - message
                      - status
                required:
                  - error
  /v2/conversations/{id}/participants:
    post:
      operationId: addParticipantToConversation
      summary: Add a contact to a conversation
      description: >-
        Adds a contact (customer or lead) as a participant to an existing
        conversation.


        ### Path Parameters


        - `id` - The conversation ID (short ID)


        ### Request Body


        | Field | Type | Required | Description |

        |-------|------|----------|-------------|

        | `participant` | object | Yes | The contact to add (see below) |

        | `participant.id` | string | No* | The Featurebase ID (24-character
        ObjectId) - matches customer or lead |

        | `participant.userId` | string | No* | External user ID from your
        system - matches customer only |

        | `participant.email` | string | No* | Email address - matches customer
        only |

        | `actingAdminId` | string | No | Admin ID performing the action (for
        attribution) |


        *At least one of `id`, `userId`, or `email` is required in the
        participant object.


        ### Lookup Priority


        1. If `id` is provided, looks up by Featurebase ID (matches both
        customer and lead types)

        2. If `userId` is provided, looks up by external user ID (matches
        customer type only)

        3. If `email` is provided, looks up by email address (matches customer
        type only)


        ### Response


        Returns the updated conversation object.


        ### Example Request (by Featurebase ID)


        ```json

        {
          "participant": {
            "id": "676f0f6765bdaa7d7d760f88"
          },
          "actingAdminId": "507f1f77bcf86cd799439011"
        }

        ```


        ### Example Request (by external userId)


        ```json

        {
          "participant": {
            "userId": "user_123"
          }
        }

        ```


        ### Example Request (by email)


        ```json

        {
          "participant": {
            "email": "john@example.com"
          }
        }

        ```


        ### Example Response


        ```json

        {
          "object": "conversation",
          "id": "12345",
          "participants": [
            { "type": "customer", "id": "676f0f6765bdaa7d7d760f88" },
            { "type": "customer", "id": "676f0f6765bdaa7d7d760f89" }
          ],
          ...
        }

        ```


        ### Version Availability


        This endpoint is only available in API version 2026-01-01.nova and
        newer.
      tags:
        - Conversations
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/FeaturebaseVersion'
        - schema:
            type: string
            minLength: 1
            maxLength: 16
            pattern: ^[a-zA-Z0-9]+$
            description: Conversation ID (short ID)
            example: '12345'
          required: true
          name: id
          in: path
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddParticipantBody'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Conversation'
        '403':
          description: |-
            Forbidden

            Possible error codes:
            - `forbidden`: Acting admin is not a member of this organization
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - authorization_error
                        description: The type of error returned
                        example: authorization_error
                      code:
                        type: string
                        enum:
                          - forbidden
                        description: Machine-readable error code
                        example: forbidden
                      message:
                        type: string
                        description: Human-readable error message
                        example: An error occurred
                      param:
                        type: string
                        description: The parameter that caused the error (if applicable)
                        example: id
                      status:
                        type: number
                        enum:
                          - 403
                        description: HTTP status code
                        example: 403
                    required:
                      - type
                      - code
                      - message
                      - status
                required:
                  - error
        '404':
          description: |-
            Not Found

            Possible error codes:
            - `conversation_not_found`: No conversation exists with this ID
            - `contact_not_found`: The contact to add was not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - invalid_request_error
                        description: The type of error returned
                        example: invalid_request_error
                      code:
                        type: string
                        enum:
                          - conversation_not_found
                          - contact_not_found
                        description: Machine-readable error code
                        example: conversation_not_found
                      message:
                        type: string
                        description: Human-readable error message
                        example: An error occurred
                      param:
                        type: string
                        description: The parameter that caused the error (if applicable)
                        example: id
                      status:
                        type: number
                        enum:
                          - 404
                        description: HTTP status code
                        example: 404
                    required:
                      - type
                      - code
                      - message
                      - status
                required:
                  - error
    delete:
      operationId: removeParticipantFromConversation
      summary: Remove a contact from a conversation
      description: >-
        Removes a contact (customer or lead) from an existing conversation.


        **Note:** You cannot remove the last participant from a conversation.


        ### Path Parameters


        - `id` - The conversation ID (short ID)


        ### Request Body


        | Field | Type | Required | Description |

        |-------|------|----------|-------------|

        | `id` | string | Yes | The Featurebase ID of the contact to remove
        (24-character ObjectId) |

        | `actingAdminId` | string | No | Admin ID performing the action (for
        attribution) |


        ### Response


        Returns the updated conversation object.


        ### Example Request


        ```json

        {
          "id": "676f0f6765bdaa7d7d760f88",
          "actingAdminId": "507f1f77bcf86cd799439011"
        }

        ```


        ### Example Response


        ```json

        {
          "object": "conversation",
          "id": "12345",
          "participants": [
            { "type": "customer", "id": "676f0f6765bdaa7d7d760f89" }
          ],
          ...
        }

        ```


        ### Error Cases


        - **400 Bad Request** - Cannot remove the last participant from a
        conversation

        - **404 Not Found** - Conversation or contact not found in participants


        ### Version Availability


        This endpoint is only available in API version 2026-01-01.nova and
        newer.
      tags:
        - Conversations
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/FeaturebaseVersion'
        - schema:
            type: string
            minLength: 1
            maxLength: 16
            pattern: ^[a-zA-Z0-9]+$
            description: Conversation ID (short ID)
            example: '12345'
          required: true
          name: id
          in: path
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RemoveParticipantBody'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Conversation'
        '400':
          description: >-
            Bad Request


            Possible error codes:

            - `invalid_request`: Cannot remove the last participant from a
            conversation
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - invalid_request_error
                        description: The type of error returned
                        example: invalid_request_error
                      code:
                        type: string
                        enum:
                          - invalid_request
                        description: Machine-readable error code
                        example: invalid_request
                      message:
                        type: string
                        description: Human-readable error message
                        example: An error occurred
                      param:
                        type: string
                        description: The parameter that caused the error (if applicable)
                        example: id
                      status:
                        type: number
                        enum:
                          - 400
                        description: HTTP status code
                        example: 400
                    required:
                      - type
                      - code
                      - message
                      - status
                required:
                  - error
        '403':
          description: |-
            Forbidden

            Possible error codes:
            - `forbidden`: Acting admin is not a member of this organization
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - authorization_error
                        description: The type of error returned
                        example: authorization_error
                      code:
                        type: string
                        enum:
                          - forbidden
                        description: Machine-readable error code
                        example: forbidden
                      message:
                        type: string
                        description: Human-readable error message
                        example: An error occurred
                      param:
                        type: string
                        description: The parameter that caused the error (if applicable)
                        example: id
                      status:
                        type: number
                        enum:
                          - 403
                        description: HTTP status code
                        example: 403
                    required:
                      - type
                      - code
                      - message
                      - status
                required:
                  - error
        '404':
          description: >-
            Not Found


            Possible error codes:

            - `conversation_not_found`: No conversation exists with this ID

            - `participant_not_found`: The contact is not a participant in this
            conversation
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - invalid_request_error
                        description: The type of error returned
                        example: invalid_request_error
                      code:
                        type: string
                        enum:
                          - conversation_not_found
                          - participant_not_found
                        description: Machine-readable error code
                        example: conversation_not_found
                      message:
                        type: string
                        description: Human-readable error message
                        example: An error occurred
                      param:
                        type: string
                        description: The parameter that caused the error (if applicable)
                        example: id
                      status:
                        type: number
                        enum:
                          - 404
                        description: HTTP status code
                        example: 404
                    required:
                      - type
                      - code
                      - message
                      - status
                required:
                  - error
  /v2/conversations/redact:
    post:
      operationId: redactConversationPart
      summary: Redact a conversation part
      description: >-
        Redacts a conversation part (message) from a conversation. Redaction
        permanently removes the message content while preserving the
        conversation structure.


        Only human message types can be redacted:

        - `user_msg` - Messages from customers/leads

        - `admin_msg` - Messages from admins

        - `email_msg` - Email messages

        - `bot_msg` - Bot messages


        System-generated conversation parts (assignments, status changes, etc.)
        cannot be redacted.


        ### Request Body


        | Field | Type | Required | Description |

        |-------|------|----------|-------------|

        | `type` | string | Yes | The type of item to redact. Currently only
        `"conversation_part"` is supported. |

        | `conversationId` | string | Yes | The conversation short ID containing
        the part to redact |

        | `conversationPartId` | string | Yes | The conversation part short ID
        to redact |

        | `actingAdminId` | string | No | Admin ID performing the action (for
        attribution) |


        ### Response


        Returns the updated conversation object.


        ### Example Request


        ```json

        {
          "type": "conversation_part",
          "conversationId": "12345",
          "conversationPartId": "67890",
          "actingAdminId": "507f1f77bcf86cd799439011"
        }

        ```


        ### Example Response


        ```json

        {
          "object": "conversation",
          "id": "12345",
          "conversationParts": [
            {
              "object": "conversation_part",
              "id": "67890",
              "partType": "user_msg",
              "bodyHtml": "",
              "bodyMarkdown": "",
              "redacted": true,
              ...
            }
          ],
          ...
        }

        ```


        ### Error Cases


        - **400 Bad Request** - Only human messages can be redacted

        - **404 Not Found** - Conversation or conversation part not found


        ### Version Availability


        This endpoint is only available in API version 2026-01-01.nova and
        newer.
      tags:
        - Conversations
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/FeaturebaseVersion'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RedactConversationPartBody'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Conversation'
        '400':
          description: |-
            Bad Request

            Possible error codes:
            - `invalid_request`: Only human messages can be redacted
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - invalid_request_error
                        description: The type of error returned
                        example: invalid_request_error
                      code:
                        type: string
                        enum:
                          - invalid_request
                        description: Machine-readable error code
                        example: invalid_request
                      message:
                        type: string
                        description: Human-readable error message
                        example: An error occurred
                      param:
                        type: string
                        description: The parameter that caused the error (if applicable)
                        example: id
                      status:
                        type: number
                        enum:
                          - 400
                        description: HTTP status code
                        example: 400
                    required:
                      - type
                      - code
                      - message
                      - status
                required:
                  - error
        '403':
          description: |-
            Forbidden

            Possible error codes:
            - `forbidden`: Acting admin is not a member of this organization
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - authorization_error
                        description: The type of error returned
                        example: authorization_error
                      code:
                        type: string
                        enum:
                          - forbidden
                        description: Machine-readable error code
                        example: forbidden
                      message:
                        type: string
                        description: Human-readable error message
                        example: An error occurred
                      param:
                        type: string
                        description: The parameter that caused the error (if applicable)
                        example: id
                      status:
                        type: number
                        enum:
                          - 403
                        description: HTTP status code
                        example: 403
                    required:
                      - type
                      - code
                      - message
                      - status
                required:
                  - error
        '404':
          description: |-
            Not Found

            Possible error codes:
            - `conversation_not_found`: No conversation exists with this ID
            - `conversation_part_not_found`: The conversation part was not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - invalid_request_error
                        description: The type of error returned
                        example: invalid_request_error
                      code:
                        type: string
                        enum:
                          - conversation_not_found
                          - conversation_part_not_found
                        description: Machine-readable error code
                        example: conversation_not_found
                      message:
                        type: string
                        description: Human-readable error message
                        example: An error occurred
                      param:
                        type: string
                        description: The parameter that caused the error (if applicable)
                        example: id
                      status:
                        type: number
                        enum:
                          - 404
                        description: HTTP status code
                        example: 404
                    required:
                      - type
                      - code
                      - message
                      - status
                required:
                  - error
  /v2/webhooks:
    get:
      operationId: listWebhooks
      summary: List webhooks
      description: >-
        Returns a list of webhooks in your organization using cursor-based
        pagination.


        ### Query Parameters


        - `limit` - Number of webhooks to return (1-100, default 10)

        - `cursor` - Cursor from previous response for pagination

        - `status` - Filter by status: "active", "paused", or "suspended"


        ### Response Format


        Returns a list object with:

        - `object` - Always "list"

        - `data` - Array of webhook objects

        - `nextCursor` - Cursor for the next page, or null if no more results


        ### Webhook Object


        Each webhook includes:

        - `id` - Unique webhook identifier

        - `name` - Human-readable webhook name

        - `url` - Webhook endpoint URL

        - `topics` - Array of subscribed event topics

        - `status` - Current status ("active", "paused", "suspended")

        - `health` - Health metrics (response times, error counts)

        - `createdAt` - Creation timestamp

        - `updatedAt` - Last update timestamp


        ### Example


        ```json

        {
          "object": "list",
          "data": [
            {
              "object": "webhook",
              "id": "507f1f77bcf86cd799439011",
              "name": "Production Webhook",
              "url": "https://example.com/webhooks",
              "topics": ["post.created", "post.updated"],
              "status": "active",
              ...
            }
          ],
          "nextCursor": "eyJpZCI6IjUwN2YxZjc3YmNmODZjZDc5OTQzOTAxMSJ9"
        }

        ```


        ### Version Availability


        This endpoint is only available in API version 2026-01-01.nova and
        newer.
      tags:
        - Webhooks
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/FeaturebaseVersion'
        - schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 10
            description: >-
              A limit on the number of objects to be returned, between 1 and
              100.
            example: 10
          required: false
          name: limit
          in: query
        - schema:
            type: string
            maxLength: 512
            description: >-
              An opaque cursor for pagination. Use the nextCursor value from a
              previous response to fetch the next page of results.
            example: eyJpZCI6IjUwN2YxZjc3YmNmODZjZDc5OTQzOTAxMSJ9
          required: false
          name: cursor
          in: query
        - schema:
            type: string
            enum:
              - active
              - paused
              - suspended
            description: Filter webhooks by status
            example: active
          required: false
          name: status
          in: query
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookList'
        '400':
          description: |-
            Bad Request

            Possible error codes:
            - `invalid_cursor`: The pagination cursor is malformed or expired
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - invalid_request_error
                        description: The type of error returned
                        example: invalid_request_error
                      code:
                        type: string
                        enum:
                          - invalid_cursor
                        description: Machine-readable error code
                        example: invalid_cursor
                      message:
                        type: string
                        description: Human-readable error message
                        example: An error occurred
                      param:
                        type: string
                        description: The parameter that caused the error (if applicable)
                        example: id
                      status:
                        type: number
                        enum:
                          - 400
                        description: HTTP status code
                        example: 400
                    required:
                      - type
                      - code
                      - message
                      - status
                required:
                  - error
    post:
      operationId: createWebhook
      summary: Create a webhook
      description: >-
        Creates a new webhook to receive event notifications.


        ### Request Body


        | Field | Type | Required | Description |

        |-------|------|----------|-------------|

        | `name` | string | Yes | Human-readable name (max 100 chars) |

        | `url` | string | Yes | Webhook endpoint URL (must be HTTPS) |

        | `description` | string | No | Optional description (max 500 chars) |

        | `topics` | string[] | Yes | Event topics to subscribe to |

        | `requestConfig` | object | No | Request configuration |

        | `requestConfig.headers` | object | No | Custom headers to send (max
        10) |


        ### Available Topics


        - `post.created` - When a new post is created

        - `post.updated` - When a post is updated

        - `post.deleted` - When a post is deleted

        - `post.voted` - When a post receives a vote

        - `changelog.published` - When a changelog is published

        - `comment.created` - When a comment is created

        - `comment.updated` - When a comment is updated

        - `comment.deleted` - When a comment is deleted


        ### Response


        Returns the created webhook object including the signing secret.


        ### Example Request


        ```json

        {
          "name": "Production Webhook",
          "url": "https://example.com/webhooks",
          "description": "Handles all production events",
          "topics": ["post.created", "post.updated", "comment.created"],
          "requestConfig": {
            "timeoutMs": 10000,
            "headers": {
              "X-Custom-Header": "value"
            }
          }
        }

        ```


        ### Example Response


        ```json

        {
          "object": "webhook",
          "id": "507f1f77bcf86cd799439011",
          "name": "Production Webhook",
          "url": "https://example.com/webhooks",
          "secret": "whsec_abc123def456ghi789",
          "topics": ["post.created", "post.updated", "comment.created"],
          "status": "active",
          ...
        }

        ```


        ### Limits


        Each organization has a maximum number of webhooks (default: 10).
        Creating a webhook when the limit is reached will return a 400 error.


        ### Version Availability


        This endpoint is only available in API version 2026-01-01.nova and
        newer.
      tags:
        - Webhooks
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/FeaturebaseVersion'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateWebhookBody'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Webhook'
        '400':
          description: >-
            Bad Request


            Possible error codes:

            - `invalid_parameter`: Invalid request parameters

            - `invalid_request`: Maximum number of webhooks reached for this
            organization
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - invalid_request_error
                        description: The type of error returned
                        example: invalid_request_error
                      code:
                        type: string
                        enum:
                          - invalid_parameter
                          - invalid_request
                        description: Machine-readable error code
                        example: invalid_parameter
                      message:
                        type: string
                        description: Human-readable error message
                        example: An error occurred
                      param:
                        type: string
                        description: The parameter that caused the error (if applicable)
                        example: id
                      status:
                        type: number
                        enum:
                          - 400
                        description: HTTP status code
                        example: 400
                    required:
                      - type
                      - code
                      - message
                      - status
                required:
                  - error
  /v2/webhooks/{id}:
    get:
      operationId: getWebhookById
      summary: Get webhook by ID
      description: >-
        Retrieves a single webhook by its unique identifier.


        ### Path Parameters


        - `id` - The webhook ID (24-character ObjectId)


        ### Response Format


        Returns a webhook object with:

        - `object` - Always "webhook"

        - `id` - Unique webhook identifier

        - `name` - Human-readable webhook name

        - `url` - Webhook endpoint URL

        - `description` - Optional description

        - `topics` - Array of subscribed event topics

        - `status` - Current status ("active", "paused", "suspended")

        - `requestConfig` - Request configuration (timeout, headers)

        - `lastStatus` - Last delivery attempt status

        - `health` - Health metrics

        - `createdAt` - Creation timestamp

        - `updatedAt` - Last update timestamp


        The response includes the webhook signing secret for payload
        verification.


        ### Example


        ```json

        {
          "object": "webhook",
          "id": "507f1f77bcf86cd799439011",
          "name": "Production Webhook",
          "url": "https://example.com/webhooks",
          "description": "Handles all production events",
          "topics": ["post.created", "post.updated"],
          "status": "active",
          "requestConfig": {
            "timeoutMs": 5000,
            "headers": {}
          },
          "lastStatus": {
            "code": 200,
            "message": "Success",
            "timestamp": "2025-01-15T10:30:00.000Z"
          },
          "health": {
            "lastResponseTime": 150,
            "avgResponseTime": 200,
            "lastSuccessAt": "2025-01-15T10:30:00.000Z",
            "errorsSinceLastSuccess": 0,
            "consecutiveFailures": 0
          },
          "createdAt": "2025-01-01T00:00:00.000Z",
          "updatedAt": "2025-01-15T10:30:00.000Z"
        }

        ```


        ### Version Availability


        This endpoint is only available in API version 2026-01-01.nova and
        newer.
      tags:
        - Webhooks
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/FeaturebaseVersion'
        - schema:
            type: string
            description: Webhook unique identifier
            example: 507f1f77bcf86cd799439011
          required: true
          name: id
          in: path
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Webhook'
        '400':
          description: |-
            Bad Request

            Possible error codes:
            - `invalid_id`: The webhook ID format is invalid
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - invalid_request_error
                        description: The type of error returned
                        example: invalid_request_error
                      code:
                        type: string
                        enum:
                          - invalid_id
                        description: Machine-readable error code
                        example: invalid_id
                      message:
                        type: string
                        description: Human-readable error message
                        example: An error occurred
                      param:
                        type: string
                        description: The parameter that caused the error (if applicable)
                        example: id
                      status:
                        type: number
                        enum:
                          - 400
                        description: HTTP status code
                        example: 400
                    required:
                      - type
                      - code
                      - message
                      - status
                required:
                  - error
        '404':
          description: |-
            Not Found

            Possible error codes:
            - `webhook_not_found`: No webhook exists with this ID
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - invalid_request_error
                        description: The type of error returned
                        example: invalid_request_error
                      code:
                        type: string
                        enum:
                          - webhook_not_found
                        description: Machine-readable error code
                        example: webhook_not_found
                      message:
                        type: string
                        description: Human-readable error message
                        example: An error occurred
                      param:
                        type: string
                        description: The parameter that caused the error (if applicable)
                        example: id
                      status:
                        type: number
                        enum:
                          - 404
                        description: HTTP status code
                        example: 404
                    required:
                      - type
                      - code
                      - message
                      - status
                required:
                  - error
    patch:
      operationId: updateWebhook
      summary: Update a webhook
      description: >-
        Updates a webhook's properties. Supports partial updates - only provided
        fields will be updated.


        ### Path Parameters


        - `id` - The webhook ID (24-character ObjectId)


        ### Request Body


        All fields are optional. Only provided fields will be updated.


        | Field | Type | Description |

        |-------|------|-------------|

        | `name` | string | Human-readable name (max 100 chars) |

        | `url` | string | Webhook endpoint URL (must be HTTPS) |

        | `description` | string/null | Description (null to clear) |

        | `topics` | string[] | Event topics to subscribe to |

        | `status` | string | "active" to reactivate, "paused" to pause delivery
        |

        | `requestConfig` | object | Request configuration |

        | `requestConfig.headers` | object | Custom headers to send (max 10) |


        ### Pausing and Reactivating Webhooks


        You can pause a webhook to temporarily stop receiving events:


        ```json

        {
          "status": "paused"
        }

        ```


        Webhooks may also be automatically paused or suspended due to delivery
        failures. To reactivate:


        ```json

        {
          "status": "active"
        }

        ```


        Reactivating a webhook resets the health metrics and allows it to
        receive events again.


        ### Example: Update Topics


        ```json

        {
          "topics": ["post.created", "post.updated", "post.deleted"]
        }

        ```


        ### Example: Update Request Config


        ```json

        {
          "requestConfig": {
            "headers": {
              "X-Custom-Header": "new-value"
            }
          }
        }

        ```


        ### Version Availability


        This endpoint is only available in API version 2026-01-01.nova and
        newer.
      tags:
        - Webhooks
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/FeaturebaseVersion'
        - schema:
            type: string
            description: Webhook unique identifier
            example: 507f1f77bcf86cd799439011
          required: true
          name: id
          in: path
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateWebhookBody'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Webhook'
        '400':
          description: |-
            Bad Request

            Possible error codes:
            - `invalid_parameter`: Invalid request parameters
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - invalid_request_error
                        description: The type of error returned
                        example: invalid_request_error
                      code:
                        type: string
                        enum:
                          - invalid_parameter
                        description: Machine-readable error code
                        example: invalid_parameter
                      message:
                        type: string
                        description: Human-readable error message
                        example: An error occurred
                      param:
                        type: string
                        description: The parameter that caused the error (if applicable)
                        example: id
                      status:
                        type: number
                        enum:
                          - 400
                        description: HTTP status code
                        example: 400
                    required:
                      - type
                      - code
                      - message
                      - status
                required:
                  - error
        '404':
          description: |-
            Not Found

            Possible error codes:
            - `webhook_not_found`: No webhook exists with this ID
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - invalid_request_error
                        description: The type of error returned
                        example: invalid_request_error
                      code:
                        type: string
                        enum:
                          - webhook_not_found
                        description: Machine-readable error code
                        example: webhook_not_found
                      message:
                        type: string
                        description: Human-readable error message
                        example: An error occurred
                      param:
                        type: string
                        description: The parameter that caused the error (if applicable)
                        example: id
                      status:
                        type: number
                        enum:
                          - 404
                        description: HTTP status code
                        example: 404
                    required:
                      - type
                      - code
                      - message
                      - status
                required:
                  - error
    delete:
      operationId: deleteWebhook
      summary: Delete a webhook
      description: >-
        Permanently deletes a webhook.


        ### Path Parameters


        - `id` - The webhook ID (24-character ObjectId)


        ### Response


        Returns a deletion confirmation object:


        ```json

        {
          "id": "507f1f77bcf86cd799439011",
          "object": "webhook",
          "deleted": true
        }

        ```


        ### Caution


        This operation is **irreversible**. The webhook and its configuration
        will be permanently deleted.

        After deletion, no events will be sent to the webhook endpoint.


        ### Version Availability


        This endpoint is only available in API version 2026-01-01.nova and
        newer.
      tags:
        - Webhooks
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/FeaturebaseVersion'
        - schema:
            type: string
            description: Webhook unique identifier
            example: 507f1f77bcf86cd799439011
          required: true
          name: id
          in: path
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeletedWebhook'
        '400':
          description: |-
            Bad Request

            Possible error codes:
            - `invalid_id`: The webhook ID format is invalid
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - invalid_request_error
                        description: The type of error returned
                        example: invalid_request_error
                      code:
                        type: string
                        enum:
                          - invalid_id
                        description: Machine-readable error code
                        example: invalid_id
                      message:
                        type: string
                        description: Human-readable error message
                        example: An error occurred
                      param:
                        type: string
                        description: The parameter that caused the error (if applicable)
                        example: id
                      status:
                        type: number
                        enum:
                          - 400
                        description: HTTP status code
                        example: 400
                    required:
                      - type
                      - code
                      - message
                      - status
                required:
                  - error
        '404':
          description: |-
            Not Found

            Possible error codes:
            - `webhook_not_found`: No webhook exists with this ID
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - invalid_request_error
                        description: The type of error returned
                        example: invalid_request_error
                      code:
                        type: string
                        enum:
                          - webhook_not_found
                        description: Machine-readable error code
                        example: webhook_not_found
                      message:
                        type: string
                        description: Human-readable error message
                        example: An error occurred
                      param:
                        type: string
                        description: The parameter that caused the error (if applicable)
                        example: id
                      status:
                        type: number
                        enum:
                          - 404
                        description: HTTP status code
                        example: 404
                    required:
                      - type
                      - code
                      - message
                      - status
                required:
                  - error
webhooks: {}
x-tagGroups:
  - name: Getting Started
    tags:
      - API Versioning
      - Authentication
      - Error Handling
  - name: Feedback
    tags:
      - Boards
      - Posts
      - Post Statuses
      - Comments
      - Custom Fields
  - name: Changelog
    tags:
      - Changelogs
  - name: Organization
    tags:
      - Admins
      - Teams
  - name: Users
    tags:
      - Contacts
      - Companies
  - name: Products
    tags:
      - Surveys
      - Help Centers
      - Conversations
  - name: Integrations
    tags:
      - Webhooks
